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PREFACE 



MANUAL OBJECTIVES 

The RSX-11M/M-PLUS Util ities Manual is a reference manual describing 
the use of 15 utilities supported on the RSX-11M and RSX-11M-PLUS 
operating systems. 



INTENDED AUDIENCE 

This manual is for all users of the RSX-11M and RSX-11M-PLUS operating 
systems . 



STRUCTURE OF THIS DOCUMENT 

Chapter 1 describes briefly each of the utilities, and explains how to 
enter command lines and how to invoke and use the utilities. 

Chapter 2 describes the Line Text Editor (EDI). 

Chapter 3 describes the Peripheral Interchange Program (PIP). 

Chapter 4 describes the File Transfer Utility Program (FLX). 

Chapter 5 describes the Disk Volume Formatter Utility (FMT). 

Chapter 6 describes the Bad Block Locator Utility (BAD). 

Chapter 7 describes the Backup and Restore Utility (BRU) . 

Chapter 8 describes the Disk Save and Compress Utility Program (DSC). 

Chapter 9 describes the File Structure Verification Utility (VFY) . 

Chapter 10 describes the Librarian Utility Program (LBR) . 

Chapter 11 describes the File Dump Utility (DMP) . 

Chapter 12 describes the File Compare Utility (CMP). 

Chapter 13 describes the Source Language Input Program (SLP). 

Chapter 14 describes the Object Module Patch Utility (PAT). 

Chapter 15 describes the Task/File Patch Program (ZAP). 
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Appendix A is a summary of the commands and switches for the 
ut il it ies . 

Appendix B describes the Cross-Ref erence Processor (CRF) . 



ASSOCIATED DOCUMENTS 

The RSX-11M/M-PLUS MCR Operations Manual describes the Monitor Console 
Routine (MCR) and its commands. The utilities can be invoked from 
MCR. This manual provides background information about MCR. 

The RSX-11M-PLUS Command Language Manual describes the DIGITAL Command 
Language (DCL) and its commands. Most of the utilities can be invoked 
from DCL. This manual provides background information about DCL. 



CONVENTIONS USED IN THIS DOCUMENT 

Use of Red Ink 

User input appears in red. Lines and prompting characters output by 
the system appear in black. 



Use of UPPERCASE Characters 

Uppercase characters in a command line indicate characters that must 
be entered as they are shown. For example, utility switches must 
always be entered as they are shown in format specifications. An 
exception is the (Set) symbol, which denotes the RETURN key. 



Use of Lowercase Characters 

Lowercase characters in a command line indicate variables for which 
the user must substitute a word or value. For example: 

filename. file type /version 

This command indicates the values that comprise a file specification; 
values are substituted for each of these variables as appropriate. 



Command Abbreviations 

Where short forms of commands are allowed, the shortest form 
acceptable is represented by uppercase characters. The following 
example shows the minimum abbreviation allowed for the EDI WRITE 
command : 

Write 

This notation means that W, WR, WRI, WRIT, and WRITE are all valid 
specifications for the WRITE command. 
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Use of Square Brackets ([]) 

Square brackets indicate optional entries in a command line or a file 
specification. Note that when an option is entered, the brackets are 
not included in the command line. 

Square brackets also are a part of the User File Directory (UFD) and 
User Identification Code (UIC) syntax ( [group, member] ) . When you use 
a UIC or UFD (in a file specification, for example), brackets are 
required syntax elements; that is, they do not indicate optional 
entries . 



Use of Braces ({}) 

Braces indicate a choice of required entries for a command line. You 
can use any of the entries enclosed in the braces, but you must 
specify one of them. 

Use of Commas (,) 

Commas are used as separators for command line parameters and to 
indicate positional entries on a command line. Positional entries are 
those elements that must be in a certain place in the command line. 
Although you might omit elements that come before the desired element, 
the commas that separate them must still be included. 



Use of At Sign (@) 

The at sign (@) invokes an indirect command file. The at sign 
immediately precedes the file specification for the indirect command 
file: 

@f ilename [ . f iletype ; vers ion] 



Use of Periods (.) 

Periods in the file specification separate the file name and file 
type. When the file type is not specified, the period may be omitted 
from the file specification. 



Use of Semicolons (;) 

Semicolons in the file specification separate the file type from the 
file version. If the version is not specified, the semicolon may be 
omitted from the file specification. 



Use of Slashes (/) 

Slashes precede switches and subswitches in the command line. When 
shown in the command line format, they should be specified as shown. 



A horizontal ellipsis indicates that the preceding item(s) can be 
repeated one or more times. 
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gTRL/X) 

The symbol EmUx) indicates that you must press the key labeled CTRL 
while you simultaneously press another key, for example, £trl/5) , 

6TRL/5j , gRL/Z) . 
(RET) 

Command lines are terminated by pressing the RETURN key unless 
otherwise indicated in the text. The form used to denote the RETURN 
key is (HD . 

Use of Shading 

Shaded portions of text describe only one operating system. Pink 
shading indicates that the text describes only RSX-11M operating 
systems. Gray shading indicates that the text describes only 
RSX-11M-PLUS operating systems. The smallest shaded portion of text 
is a paragraph. The text that is not shaded describes both operating 
systems . 
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SUMMARY OF TECHNICAL CHANGES 



The following is a list of the technical changes (such as new 
functionality, and new and revised switches) by utility, in the order 
in which the utility appears in this manual. 



Peripheral Interchange Program (PIP) 

ANSI magnetic tapes are now supported. 

& - Ampersand (new) - Separates each command when several 
commands are specified in the same command line. 

% - Wildcard (new) - Denotes exactly one character in the file 
name and/or file type of an input file specification. 

/CD - Creation Date switch (revised) - Can be set as the default 
(instead of /-CD). 

/DD - Default Date switch (new) - Restricts file searches to 
files created during a specified period of time. 

/DF - Default switch (revised) - Specified with no arguments, it 
returns the default device to SYO: and the UFD to the UIC from 
which PIP was invoked. 

/EX - File Exclusion switch (new) - Excludes one file 
specification's worth of files during a file search. 

/FR - Free Blocks switch (revised) - Displays the amount of 
available space on a specified volume, the largest contiguous 
space on that volume, and the number of available file headers. 

/ID - Identity switch (revised) - Identifies the version of PIP 
being used and if PIP is linked to ANSI FCS. 

/TD - Today switch (new) - Restricts file searches to files 
created on the current day. 



File Transfer Utility Program (FLX) 

The TU78 magnetic tape is now supported. 

/DNS:6250 - Density switch (revised) - Specifies a density of 
6250 bpi to support the TU78 magnetic tape. 



SUMMARY OF TECHNICAL CHANGES 



Disk Volume Formatter Utility (FMT) 

The RM05 disk is fully supported. FMT treats the RM05 as a 
larger RM03. 

DL:-type devices are supported, and some corrupted DL:-type disk 
cartridges can be made usable again. 

/VE - Verify switch (revised) - is now the default operation. 

/-VE, /NOVE, /-VERIFY, /NOVERIFY - No Verify switch (new) 
Inhibits the default verification operation. 

/DENSITY, /MANUAL , /VERIFY (new) - Switch synonyms for /DENS, 
/MAN, and /VE respectively. 



Bad Block Locator Utility (BAD) 

A multiheader BADBLK. SYS file is now supported. The maximum 
allowable retrieval pointers in the bad block descriptor file 
have been expanded from 102 to 126 for non- last- track devices. 

The updated stand-alone version of BAD supports the following 
devices: the RM05, RM80, and RP07 disk packs, and the RA80 fixed 
media disk. 

/ALO:volume label - Allocate switch (new) - Prompts for blocks to 
be allocated to BADBLK. SYS and to be entered in the bad block 
descriptor file. 

/PAT=m:n - Pattern switch (new) - Specifies the double-word data 
pattern used to locate bad blocks. 



Backup and Restore Utility (BRU) 

BRU now supports multivolume backup and restore operations using 
the /IMAGE switch. 

BRU now supports the following devices: RA60/RA81/RC25/RD51/RX50 
disks, RL11/RL02 cartridge disks, RH70/RM05/RM80/RP07 disk packs, 
UDA50/RP07 disk packs, TM78/TU78 magnetic tapes, ML11 electronic 
memory, and TS11/TSV05/TU80 magnetic tapes. 

Disk volumes with multiheader index files (structure level 402) 
are supported. 

There are now two stand-alone BRU systems. BRU64K is the 
stand-alone version for the RSX-11M and BRUSYS is the stand-alone 
version for RSX-11M-PLUS . 

/DENSITY - Density switch (revised) - For TU78 magnetic tapes, 
you can specify a density of 1600 or 6250 bpi (6250 is the 
default bpi) . 

/IMAGE :option - Image switch (new) - Specifies that you want to 
do a multiple disk-to-disk backup or restore operation. 

/UFD - User File Directory switch (new) - Directs BRU to create a 
UFD (if it does not already exist) on a mounted output volume, 
and then to copy into it the files from the same UFD on the input 
volume . 
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SUMMARY OF TECHNICAL CHANGES 



Disk Save and Compress Utility Program (DSC) 

There are two new stand-alone versions of DSC: DSCSYS and 
DSC64K. 

DSCSYS is a combination of DSCS8 and DSCS16 . This version 
requires 28K words to run and a maximum blocking factor of 4. 
DSCSYS supports the following new devices: the RP07 disk, the 
RA08 fixed media disk, and the TU78 magnetic tape. 

DSC64K is essentially an RSX-11M system with BAD, FMT, DSC, and 
CNF fixed in memory. The maximum blocking factor is 4 and DT, 
DX, DY, DD, DF, and DS devices are not supported. 

DSC now supports up to 64K files on a volume. 

/BAD=OVR - Override option (new) - Ignores the bad block 
descriptor area and accesses the last good block on the next to 
last track of the disk to obtain the data to create BADBLK. SYS . 

/BAD=MAN : OVR - Manual Override option (new) - Allows manual entry 
of bad block data to the bad block file BADBLK. SYS. 

/DENS=6250 - Density switch (revised) - Creates magnetic tapes at 
6250 bpi . The /DENS: 6250 option is valid with TU78 magnetic 
tapes only. 



File Structure Verification Utility Program (VFY) 

/DV - Directory Validation switch (new) - Validates directories 
against the files they list. 

/HD - Header Delete switch (new) - Recognizes and deletes bad 
file headers on a volume. The /AL subswitch allows bad headers 
to be automatically deleted with no user intervention. 



File Dump Utility Program (DMP) 

Multiple- format dumps are supported. Any or all of the format 
switches can be specified in a command line. 

ANSI magnetic tapes are supported. 

/LC - Lower Case switch (new) - Specifies that the data should be 
dumped in lowercase characters. 

/OCT - Octal switch (new) - Specifies that the data should be 
dumped in octal format in addition to other formats. 

/SB:n or /SB:-n - Specifies the number of blocks DMP space Blocks 
sv/itch (new) - Spaces forward or backward on a tape. 

/SF:n or /SF:-n - Space Files switch (new) - Specifies the number 
of end-of-file (EOF) marks DMP spaces forward or backward on a 
tape . 
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File Compare Utility (CMP) 

CMP's default output device/file is now TI : . 

Any unspecified portions of the second input file specification 
default to the specifications for the first input file. 



Source Language Input Program (SLP) 

/SQ - Sequence switch (new) - Sequences the lines in the output 

file so that they reflect the line numbers of the original input 
file. 

/RS - Resequence switch (new) - Resequences the lines in the 
output file. 

/NS - No Sequence switch (new) - Does not sequence lines in the 

output file. New lines are indicated by the audit trail. 



Task/File Patch Program (ZAP) 

Four types of task image files are supported: 

• Regular task image files (including those mapped to resident 
and supervisor mode libraries) 

• Multiuser task image files (RSX-11M-PLUS only) 

• I- and D-space (instruction and data space) tasks 
(RSX-11M-PLUS only) 

• Resident libraries 

Resident libraries can be changed in task image mode. ZAP finds 
the segments and allows you to make changes in both absolute mode 
and task image mode. 

/LI - List switch (revised) - Includes read-only segments of a 
task in its segment table. ZAP finds the starting address and 
allows you to make changes in both absolute mode and task image 
mode. For I- and D-space tasks, the /LI switch lists the 
starting block number and the address boundaries of each segment. 
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CHAPTER 1 
INTRODUCTION 



The RSX-11M and RSX-11M-PLUS operating systems provide several kinds 
of utilities for your use. Utilities are programs that allow you to 
work with different kinds of files and the contents of those files, 
and also with different kinds of media (such as disks, magnetic tapes, 
and cassettes). The RSX-11M/M-PLUS utility programs are listed and 
described briefly in Section 1.1; reference information for each 
utility is presented in a separate chapter of this manual. Two 
appendixes are also included to provide you with a summary of commands 
and switches for the utilities and to describe the Cross-Ref erence 
Processor (CRF) , which is used with the MACRO-11 assembler and the 
Task Builder. 

In addition to summarizing the RSX-11M/M-PLUS utilities, this 
introduction : 

• Describes how to enter RSX-11M/M-PLUS command lines and file 
specifications (Sections 1.2 and 1.3) 

• Describes how to invoke utilities and enter command lines to 
them (Section 1. 4) 

• Describes how to use indirect command files (Section 1.5) 



1.1 RSX-11M/M-PLUS UTILITY PROGRAMS 

This manual provides reference information for the following 
RSX-11M/M-PLUS utilities: 

Line Text Editor (EDI) 

Peripheral Interchange Program (PIP) 

File Transfer Utility Program (FLX) 

Disk Volume Formatter Utility (FMT) 

Bad Block Locator Utility (BAD) 

Backup and Restore Utility (BRU) 

Disk Save and Compress Utility Program (DSC) 

File Structure Verification Utility (VFY) 

Librarian Utility Program (LBR) 

File Dump Utility (DMP) 
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File Compare Utility (CMP) 
Source Language Input Program (SLP) 
Object Module Patch Utility (PAT) 
Task/File Patch Program (ZAP) 
The following sections briefly describe each utility. 

Note that the utilities described in this manual are not the only 
programs on RSX-11M and RSX-11M-PLUS that are used as or considered to 
be utilities. TKB, CDA, and MAC are examples of other utility-like 
programs. Some programs, such as the editor EDT f are common across 
different operating systems. These other programs are documented 
elsewhere in the RSX-11M/M-PLUS documentation set. Refer to the 
RSX-11M/RSX-11S or RSX-11M-PLUS Information Directory and Index for 
information on what programs are available and where they are 
described . 



1.1.1 Line Text Editor (EDI) 

EDI is a line-oriented, interactive editor used to create and maintain 
text and source files. ( The RSX-11M/M-PLUS Guide to Program 
Development gives specific information about using EDI to create and 
maintain program source files.) 



1.1.2 Peripheral Interchange Program (PIP) 

PIP copies files and performs several file control functions, such as 
concatenating, renaming, spooling, listing, deleting, and unlocking. 



1.1.3 File Transfer Utility Program (FLX) 

FLX is a file transfer and format conversion program that transfers 
files between DOS-11, RT-11, and Files-11 volumes, with some 
restrictions . 



1.1.4 Disk Volume Formatter Utility (FMT) 

FMT formats and verifies several types of Files-11 disks. FMT writes 
and verifies sector headers, sets the density for flexible disks, and 
allows spawning of the Bad Block Locator Utility (if your system 
allows spawned tasks) . 



1.1.5 Bad Block Locator Utility (BAD) 

BAD determines the number and location of bad blocks on a volume. The 
information gathered from running BAD on a volume can be used in 
different ways when that volume is initialized. 
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1.1.6 Backup and Restore Utility (BRU) 

BRU transfers files from a Files-11 volume to one or more backup 
volumes (including non-Files-11 volumes) and retrieves files from the 
backup volume (or volumes) . BRU is faster than DSC (see Section 
1.1.7) in most areas. Also, BRU compresses data, the volumes do not 
have to be initialized, and incremental backups are possible. 



1.1.7 Disk Save and Compress Utility Program (DSC) 

DSC copies Files-11 disk files to disk or tape and from DSC-created 
tape back to disk. While copying the files, DSC also consolidates the 
data storage area and writes files in contiguous blocks unless it 
encounters a bad block. DSC can be run either on-line or stand-alone. 



1.1.8 File Structure Verification Utility (VFY) 

VFY is a disk verification program that verifies the consistency and 
validity of the file structure on a Files-11 volume. 



1.1.9 Librarian Utility Program (LBR) 

LBR is a library maintenance program that creates, displays, and 
modifies library files. LBR can process macro, object, and universal 
1 ibrar ies . 



1.1.10 File Dump Utility (DMP) 

DMP is a file listing program that allows you to examine the contents 
of a file or volume of files. DMP also provides options that control 
the format of the contents. 



1.1.11 File Compare Utility (CMP) 

CMP compares two text files, record by record, and lists the 
differences between the two files. 



1.1.12 Source Language Input Program (SLP) 

SLP is a noninteractive editing program that is used to maintain and 
audit source files. 



1.1.13 Object Module Patch Utility (PAT) 

PAT updates, or patches, relocatable binary object modules. 
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1.1.14 Task/File Patch Program (ZAP) 

ZAP is a patch utility that examines and directly modifies locations 
in a task image file or data file. 



1. 2 COMMAND LINES 

The general format for command lines in most of the RSX-1 1M/M-PLUS 
utilities is: 

outfile[... / outfile]=infile[...,infile]© 

The variables outfile and infile are file specifications for the 
output and input files to be operated on by the utility. (File 
specifications are described in Section 1.3.) 

This general format varies from utility to utility. Some use the 
entire command line and others use abbreviated forms of the command 
line. For some other utilities (such as BRU) , the format is 
different. The syntax for each utility is described in the chapter 
that describes that utility. Most of the utilities also accept 
indirect command files containing command lines to the utility, as 
described in Section 1.5. 



1.3 FILE SPECIFICATIONS 

In the command line format described in Section 1.2, outfile and 
infile represent file specifications. The number of file 
specifications you can enter depends on the utility. The maximum 
terminal line length depends on the size of the output buffer for your 
terminal (the default length is 80 characters) . 

The format for entering file specifications is: 

ddnn : [g ,m] filename .type ; version/switch. . ./subswi tch. . . 

ddnn: 

The physical or logical device unit containing the desired 
volume. The name consists of two or three ASCII characters 
followed by an optional 1-, 2-, or 3-digit octal number and a 
colon, for example, DM0:, or TT116:. 

The default is the user's system device, SY: . 

The User File Directory (UFD) listing the desired file or files. 
The variables g and m are octal numbers from to 377 that 
represent the group and member numbers, respectively, of the 
file's owner. The brackets are a mandatory part of the UFD 
syntax . 

The default is the current UIC (User Identification Code) to 
which your terminal is set. 

See the RSX-1 1M/M-PLUS MCR Operations Manual or the 
RSX-1 1M/M-PLUS Command Language Manual for more information on 
UICs and UFDs. 
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filename 



The name of the file. File names can be from one to nine 
characters in length. 

If you want to include special characters in the file name (for 
example, semicolons or exclamation marks) , place double quotation 
marks around the name. If you use only one double quotation 
mark, MCR or DCL assumes an American National Standard X. 327-1978 
file name. (See the RSX-11M/M-PLUS I/O Operations Manual for 
more information on double quote support.) Note that not all 
utilities or other tasks allow special characters. 

There is no default. 



The file type of the file. The file type provides a convenient 
means for distinguishing different forms of the same file. For 
example, a FORTRAN source program file might be named COMP.FTN 
and the object file for the same program might be named COMP.OBJ. 
In this way, the file type identifies the nature of the contents 
of the file. 

File type and file name are separated by a period. The file type 
may not be specified or can be up to three alphanumeric 
characters in length. The default for a file type depends on the 
utility or task you are working with and if the file is an input 
or output file. 

See the RSX-11M/M-PLUS MCR Operations Manual or the 
RS X-11M/M-PLUS Command Language Manual for a list of standard 
file types. 



An octal number that specifies different versions of the same 
file. For example, when a file is created, it is assigned a 
version number of 1 by default. Thereafter, each time the file 
is opened and unless you specify otherwise, the file system 
creates a new file with the same file name and file type, but 
with a version number incremented by 1. Version numbers range 
from 1 through 77777(8). However, you can also use to specify 
the highest numbered version and -1 to specify the lowest 
numbered version (0 is the default) . If a file has a version 
number of 77777, no more versions of it can be created. 

Version number and file type are separated by a semicolon. The 
default is the latest version. 

/switch (also /qualifier) 

An ASCII name specifying a switch (or qualifier in BRU) 

associated with a function to be executed by the utility. Most 

utility functions are implemented by means of switches and 
subswitches. Switches can take one of three forms: 



type 



version 



/sw 



invokes the switch function 



/-sw 



negates the switch function 



/NOsw 



negates the switch function 



Switches can also take values in the form of ASCII strings and 
numeric strings. The values modify the function of the switch. 
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Most numeric values are octal by default. To specify a decimal 
number, terminate the number with a decimal point. Values 
preceded by a pound sign (#) are octal; this optional notation 
provides explicit specification of octal values. Any number can 
be preceded by either a plus (+) or minus (-) sign; plus is the 
default. Where explicit octal notation (#) is used, the sign, if 
specified, must precede the pound sign. 

The following are examples of valid switch specifications: 
/SW: 27. :MAP: 29. 
/-SW 

/NOSW: -#50: SWITCH 

/subswitch 

An ASCII name specifying a subswitch associated with a switch. 
Subswitches provide a subset of functions related to the main 
switch function. The following is an example of a subswitch 
specification : 

PIP>[200, 200] *.*; */PR/F0 © 

In this example, /FO is a subswitch applied to the /PR switch. 

Syntactically, subswitches are identical to switches. The rules 
for entering switches also apply for entering subswitches. 



1.4 INVOKING THE UTILITIES 

You invoke a utility from the command line interpreter (CLI) 
environment. The CLI can be the Monitor Console Routine (MCR) , the 
DIGITAL Command Language (DCL) , or an alternate user-written CLI. For 
more information on MCR, see the RSX-11M/M-PLUS MCR Operations Manual . 
For more information on DCL, see the RSX-11M/M-PLUS Command Language 
Manual . 

To determine whether you are using MCR or DCL or another CLI, type 
CTRL/C, which returns the explicit monitor prompt: MCR> or DCL> or 
CLI>. 

You can work with a utility directly (interactively) or by means of 
indirect command files. For systems in which all utilities are 
installed, you can use any of three methods to invoke a utility. 
Sections 1.4.1 describes these methods. For systems in which not all 
utilities are installed, you can use the method described in Section 
1.4. 2. 

Section 1.5 describes how to invoke a utility that can then accept 
commands from an indirect command file. 

You can invoke a utility when MCR or DCL prompts you. The MCR prompts 
are : 

> or (if you type CTRL/C first) MCR> 
The DCL prompts are: 

> or (if you type CTRL/C first) DCL> 
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In MCR, the utilities are always invoked by their 3-character names. 
DCL, however, has commands that access utilities transparently to the 
user. You do not have to explicitly specify the utility to use it. 
For example, the DCL command DIFFERENCES invokes the File Compare 
Utility (CMP); and the DCL commands COPY, DELETE, and PURGE invoke 
the Peripheral Interchange Program (PIP). This transparent access to 
utilities covers most common utility needs for DCL users. If you use 
these DCL commands, the general format for specifying files is: 

>command [/qual if iers] infile outfile 

DCL users can also use any MCR command forms by using the DCL command 
MCR (or MC) . 



1.4.1 Invoking Installed Utilities 

RSX-11M/M-PLUS systems provided in distribution kits do not have any 
utilities installed. Once the system has been generated, the system 
manager usually installs any commonly used utilities. Use the MCR TAS 
or DCL SHOW TASKS /INSTALL commands to see which utilities are 
currently installed in the system. If the utility you want to use is 
not installed, any privileged user can install it with the MCR or DCL 
INSTALL command. Once the utility is installed, you can invoke it. 

The following sections describe the three primary methods you can use 
to invoke installed utilities. 



1.4.1.1 Invoking a Utility and Returning Control to MCR - Use one of 

the following forms of command lines to invoke a utility to execute a 
function and then return control directly to MCR: 

>utilityname command-line 

or 

MCR>ut il ityname command-line 

Using this method to invoke the utility allows you to enter a single 
command for execution. The utility is installed, the command is 
executed, and control returns to MCR. (The method described in the 
following section allows you to enter more than one command line 
because control returns to the utility rather than to MCR.) 

Two exceptions to this command format are the SLP and ZAP utilities. 
You must first invoke these utilities and then enter the command lines 
as described in Section 1.4.1.3. (However, you can specify 

>SLP @ind irectcommandf ile 

or 

>ZAP @indirectcommandf ile 
See Section 1.5 for more information.) 



1-7 



INTRODUCTION 



1.4.1.2 Invoking a Utility and Returning Control to DCL - Use one of 

the following forms of command lines to invoke a utility to execute a 
function and return control directly to DCL: 

>commandname command-line 

or 

>MCR utilityname command-line 



Using these methods to invoke the utility allow you to enter a single 
command for execution. The utility is installed, the command is 
executed, and control returns to DCL. With the first method, the DCL 
command transparently accesses the utility (see Section 1.4). 

Two exceptions to this command format are the SLP and ZAP utilities. 
You must first invoke these utilities and then enter the command lines 
as described in Section 1.4.1.3. (However, you can specify 

>SLP @indirectcommandf ile 

or 

>ZAP @indirectcommandf ile 
See Section 1.5 for more information.) 



1.4.1.3 Invoking and Passing Control to a Utility - Use one of the 

following forms of command lines to invoke an installed utility and 
pass control to it: 

For MCR: 

>ut il ityname 
For DCL: 

>MCR utilityname 

These commands do not execute a function; rather, they make a utility 
available for execution of more than one function without returning 
control to MCR or DCL. When invoked using one of these forms, the 
utility responds with the prompt: 

util ityname> 

You can then enter the command line that specifies the function you 
want executed. For example, if you are executing a PIP function, PIP 
displays the prompt: 

PIP> 

To terminate the utility and return to MCR or DCL, type CTRL/Z. 
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1.4.2 Invoking Uninstalled Utilities 

You can use the following method to invoke an uninstalled utility. 
This method is useful for smaller systems in which not all utilities 
are installed. This method uses either the MCR RUN command or the DCL 
RUN command to invoke the utility. 

The method invokes the utility by means of the following command: 
>RUN $utilityname 

The dollar sign ($) directs MCR or DCL to search the system directory 
for the utility and to bring it into storage. On RSX-11M-PLUS , if the 
utility is not in the system directory, MCR or DCL then searches in 
the library directory and invokes the utility from there. 

When the utility gains control, it displays the prompt: 

util ityname> 

Then it waits for you to enter a command line. The utility continues 
to prompt you after each command line is executed. To terminate the 
utility,, enter CTRL/Z. Control is then returned to MCR or DCL. 

A variation of this method allows the utility to run under a UIC other 
than the current UIC: 

For MCR: 

>RUN $utilityname/UIC=[g,m] 
For DCL: 

>RUN/UIC: [g,m] $utilityname 

When the utility gains control, it prompts for functions to execute 
until you enter CTRL/Z. 



1.5 USING INDIRECT COMMAND FILES 

An indirect command file normally contains a sequence of command lines 
that are interpreted by a task (usually a system-supplied task such as 
a utility, the MACRO-11 assembler, or the Task Builder). These 
command lines appear in the indirect command file exactly as you would 
enter them from your terminal. 

The command lines contained in the indirect command file are executed 
when the indirect command file is invoked. If you invoke the file 
from MCR or DCL, each command line must begin with the name of the 
utility or command you want to use. If you invoke the file from the 
utility itself, the command lines do not begin with the name of the 
utility, but they must all be legal for that utility. 

For example, an indirect command file might contain the following 
series of PIP command lines: 

=DE52: [303, 24 ] TESTPREP. CMD 
TESTPREP.*; */LI 
TESTPREP. */PU: 2 
*.CMD/SP 
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To invoice the indirect command file (PIPCMDS.CMD), enter one of the 
following sets of commands: 

For MCR: 

>PIP @PIPCMDS.CMD(H) 

or 

>PIP(H) 

PIP>@PIPCMDS®) 
or 

>RUN $PIP(Rg) 

pip>@pipcmds m 

For DCL: 

>RUN $PIP© 

pip>@pipcmds m 

or 

>MCR PIP @PIPCMDS@ET) 
or 

>MCR PIP© 

pip>@pipcmds m 

In this example, PIP is invoked and accesses the file PIPCMDS.CMD, 
which contains the sequence of PIP command lines. Because PIP is 
invoked first, the command lines in the file do not have to begin with 
PIP. PIP executes the command lines and returns control to MCR, DCL, 
or PIP, depending on which command set you use. 

RSX-11M and RSX-11M-PLUS also allow you to use indirect command files 
that contain MCR or DCL commands. The command lines do not begin with 
MCR or DCL; they must only be legal for the CLI. You invoke the 
indirect command file by entering only the file specification preceded 
by the at sign (@) in response to the prompt (in this case, the MCR 
prompt) : 

> @ i nd i r ec tcommand file 

The default values for indirect command file specifications are: 

• device - SY: 

• [g/m] - the current UIC 

• file name - no default; must be specified 

• file type - . CMD 

• version - the latest version of the file 

For complete information on how to use indirect command files, see the 
RSX-11M/M-PLUS MCR Operations Manual . 
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CHAPTER 2 
LINE TEXT EDITOR (EDI) 



EDI is a line-oriented editor that allows you to create and modify 
text files. EDI operates on most ASCII text files. It is frequently 
used to create and maintain FORTRAN or MACRO-11 source files. 

EDI accepts over 50 commands that determine its mode of operation and 
control its actions on input files, output files, and working text 
buffers. The commands fall into the following seven categories: 

• Setup commands select operating conditions, close and open 
files, and select data modes. 

• Locator commands control the position of the current line 
pointer and thus determine which text line is acted upon. 

• Text modification commands change text lines. 

• Macro commands define, store, recall, and use sequences of EDI 
commands . 

• File input and output commands transfer text to and from 
input, output, and saved files. 

• Device output commands send output to a terminal or a printer. 

• Close and exit commands terminate editing operations. 

Commands are categorized in this chapter as Basic EDI Commands 
(Section 2.2), EDI Commands: Function Summary (Section 2.3), and EDI 
Commands: Detailed Reference Summary (Section 2.4). Restrictions, 
system device considerations, and error messages for these commands 
are discussed in Sections 2.5 and 2.6. 



2. 1 USING EDI 

This section gives background information about EDI that is important 
for you to know before you read the command descriptions. 



2. 1. 1 Invoking EDI 

You can invoke EDI using any of the methods for invoking a utility 
described in Chapter 1. If any format except ">EDI filespec" is used, 
EDI issues the following prompt: 

EDI> 
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At this point, you must enter the file specification for the file to 
be edited. 



2.1.1.1 Entering File Specifications - Enter a file specification in 
the following format: 

ddnn: [ufd] f ilename.f iletype ;version 

The abbreviation "filespec" is used throughout this chapter to denote 
a file specification that you supply. 

If the file specification is a new file (that is, the file specified 
cannot be found on the specified device) , EDI assumes that you wish to 
create a new file with the given file name. EDI then prints the 
following comment lines: 

[CREATING NEW FILE] 
INPUT 

and enters input mode. (EDI control modes are described in Section 
2. 1. 2. ) 

If the message FILE DOES NOT EXIST is printed, it means that the User 
File Directory corresponding to the specified UIC is nonexistent. 

EDI does not accept indirect command file specifications. 

If you specify an existing file name, EDI prints: 

[OOOnn LINES READ IN] 

PAGE 0] 

* 

and waits in edit mode for you to issue the first command. 

If the W >EDI filespec" format is used, the prompt (EDI>) is not issued 
and EDI starts up in either input or edit mode, depending on the file 
name specified — input mode if the file name is new, edit mode if the 
file name already exists. 

After EDI has identified the input file and created the output file, 
it is ready for commands. In edit mode, the first line available for 
editing is one line above the first line of the input file or the 
block buffer. Therefore, you can insert text at the beginning of the 
input file or the block buffer by issuing an INSERT command. To 
manipulate the first line of text, on the other hand, you must issue a 
NEXT command to make that line available. 



2.1.1.2 Defaults in File Specifications - EDI uses a default if any 
of the elements of the file specification, except the input file name, 
is omitted. In general, EDI processing creates an output file. When 
you are modifying an existing file, EDI uses that file and your 
modifications to create an output file. When the editing session is 
complete, the output file usually has the same file specification as 
the input file, except the file system renumbers the version to one 
greater than the previous version. The default values for input and 
output files are listed in Table 2-1. 
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Table 2-1 
EDI Default File Specifications 



Elejment 


Default Value 
for Input File 


Default Value 
for Output File 


ddnn : 


SYO: 


Same as input device 


[ufd] 


UFD under which EDI 
is currently running 


Same as input [ufd] 


filename 


No default — must 
be specified 


Same as input file name 


f iletype 


Unspecified 


Same as input file type 


; version 


Latest version 


Latest version + 1 



2.1.2 Control Modes: Edit and Input 

EDI runs in two control modes: 

• Edit mode (command mode) 

• Input mode (text mode) 

Edit mode is invoked automatically when you specify an existing file. 

In edit mode, EDI issues an asterisk (*) as a prompt. EDI acts upon 
commands and data to open and close files; to bring lines of text 
from an open file; to change, delete, or replace information in an 
open file; or to insert single or multiple lines anywhere in a file. 

Input mode is invoked automatically at program startup if you specify 
a nonexistent file. 

When in input mode, EDI does not issue an explicit prompt. Lines that 
you enter at the terminal are treated as text and are inserted into 
the output file. When you complete each input line by pressing the 
RETURN key, EDI sends a line feed to the terminal. 

To switch from edit mode to input mode, enter the INSERT command and 
press the RETURN key. To return to edit mode, press the RETURN key as 
the only character on an input line. EDI will issue the asterisk 
prompt, signifying edit mode. 



2.1.3 Text Access Modes 

EDI provides two modes you can use to access and manipulate lines of 
text in the input file. (A line is defined as a string of characters 
terminated by pressing the RETURN key.) The two modes are: 

• Line-by-Line Mode allows access to one line of text at a time. 
Backing up is not allowed. 

• Block Mode allows free access within a block of lines, on a 
line-by-line basis. Backing up within a block is allowed. 
Backing up to the previous block is not allowed. 

Block mode is the default text access mode. 
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In addition to these two text access modes, EDI provides a way to 
process text "pages." This feature is described in Section 2.1.3.3. 



2.1.3.1 Line-by-Line Mode - In this mode, a single line is the unit 
of the input file available for modification. Line-by-line mode is 
entered by issuing a BLOCK OFF command and is terminated by issuing a 
BLOCK ON command. 

The single available line — the current line — is specified by a 
pointer, which you can move sequentially through the file, starting 
just before the first line in the file. You can manipulate the line 
pointer using the locator commands and the text modification and 
manipulation commands discussed later in this chapter. However, you 
cannot easily direct the pointer backward within the file. 

When you open a file at the beginning of an editing session, you can 
specify that the first line be brought into memory and made available 
for modification. This line remains in memory until you request that 
a new line be brought in. The pointer then moves down the file until 
the line you requested is encountered. That line is brought into 
memory and, as the current line, can be modified. When a new line is 
brought in, the previous line is written into the output file, as are 
all lines that may be passed over in reaching the new current line. 

Once the pointer moves past a line, that line is no longer accessible 
unless you enter a TOF or TOP command (described in Section 2.4). TOF 
causes the input and output files to be closed, and the output file to 
become the new input file. TOF also ends line-by-line mode. 



2.1.3.2 Block Mode - In this mode, a portion of the input file is 
held in a buffer for editing until you request that the contents of 
the buffer be added to the output file. 

In block mode, you can access lines of text backward as well as 
forward within the buffer. Thus, you can back up to a previously 
edited line without having to reprocess the entire block or file and 
without having to issue a TOF command. 

When you finish editing a block, you can write it out and read in the 
next block with the RENEW command. However, you cannot access a 
previously edited block except by using TOF. 

EDI buffer space is computed dynamically at run time. The number of 
lines initially read into the buffer is computed by using the formula: 

buf f ersi ze/1 32 

A block is the number of lines read into the buffer by a RENEW or READ 
command. This number is either: 

1. Specified with the SIZE command (default is 38 lines if the 
SIZE command is not issued), 

or 

2. Determined by the presence of a form feed at a point in the 
text where the number of lines is less than that specified in 
the SIZE command (or its default value, if SIZE was not 
issued) . 
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When the current line pointer reaches End-Of -Block, the message 
[*EOB*] is displayed and the current line pointer points to the last 
line in the block. To move the current line pointer to the top of the 
block, use TOP. 

Table 2-2 briefly summarizes the differences between line-by-line and 
block mode. Regardless of the editing mode, the line pointer always 
points to the first character in the line. 



Table 2-2 

Line-by-Line and Block Mode Differences 



— — _______________ 

Line-by-Line Mode 


Block Mode 


One line is available for 
modification at a time. 

Lines can only be 
accessed forward through 
the file. 

Search commands can 
search the entire file. 


A block of lines is available 
for modification at a time, on 
a line-by-line basis. 

Lines can be accessed forward 
and backward within a block. 

Search commands can search only 
the block in memory. To search 
more data, you must read in 
another block. 



2.1.3.3 Processing Text in Pages - EDI provides features that allow 
you to access portions of a text file by page. A page is a segment of 
text delimited by form feed characters (the last page in a file is 
terminated by the end-of-file marker) . 

Two commands are provided to handle paged text: FF, which defines a 
page boundary by inserting a form feed, and PAGE, which accesses a 
page of text. (The commands PAGE FIND and PAGE LOCATE do not refer to 
form feed-delimited pages — they are actually global searches.) 

EDI handles paged text in block mode. If block mode is not already in 
effect, it is entered when you issue a PAGE command. 

If a form feed is encountered in text during a READ or RENEW 
operation, the page thus delimited, for purposes of the READ or RENEW 
command, is interpreted as a block. 

The message [PAGE n] , issued after a READ or RENEW operation, gives 
the value of EDI's page counter. If your text contains no form-feed 
characters, the count is zero until the last block in the file is read 
into the buffer. Upon encountering the end-of-file (EOF), EDI 
increments the page count to 1. 



2. 1. 4 Text Files 

The following sections describe how data may be added to files and the 
operations performed on output files. 
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2.1.4.1 Input and Secondary Files - EDI accepts input from the 
f ol lowing : 

• The input terminal (that is, commands and text entries) 

• Files-11 volumes that contain any of the following: 

- The file to be edited 

- A secondary file 

- A save file 

- A macro file 

The input file is always preserved. 1 Any system failure, EDI failure, 
or lack of space on the output volume does not cause the loss of the 
input file. Only the output file is affected. In cases of failure, 
the output file is not completely destroyed. Instead, it becomes a 
truncated version of the input file containing all of the edits to the 
point of failure. 

In general, the current block buffer is not written to disk when an 
error of this type occurs. 



2.1.4.2 Output Files - The output file defaults to the input file 
device, directory file name, and file type specifications. The 
version number is incremented by one. 

If you wish to change any of these parameters (except device and 
directory) , specify a new file specification when closing a file or 
exiting at the end of an EDI session. 



2.1.5 Terminal Conventions 

RSX-11M/M-PLUS and EDI provide terminal keyboard functions that allow 
you to: 

• Delete characters on an input line 

• Delete an entire input line 

• Move the current line pointer forward in a file 

• Move the current line pointer backward in a file 

• Terminate an editing session and return control to your CLI 
(for example, MCR or DCL) 



2.1.5.1 Character Erase (DELETE or RUBOUT; CTRL/R) - Pressing the 
DELETE key (marked RUBOUT on some terminals) deletes individual 
characters if used before the RETURN key is pressed. During editing 
operations, DELETE does not affect previously prepared text. 



1. To delete the input file, use the CLOSE-AND-DELETE command or the 
EXIT-AND-DELETE command, or use PIP (see Chapter 3). 
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When the DELETE key is pressed, it is echoed first as a backslash (\) 
and is followed by the previously typed character. Each successive 
DELETE results in the echo of an earlier typed character. When the 
first non-DELETE character is typed, it is echoed as a backslash 
(closing the DELETE sequence) followed by the typed character. For 
example : 

First DELETE typed MISTKAE\E 
Second DELETE MISTKAE\EA 
Third DELETE MISTKAE\EAK 
First non-DELETE MISTKAE\EAK\AKE 

For some CRT terminals, DELETE (or RUBOUT) works in a more obvious 
way. Each DELETE causes the cursor to backspace, erasing the previous 
character. Your CRT terminal may work this way if a certain option 
was selected when your system was generated. 

Another useful system generation option is CTRL/R. If this option was 
selected, your system responds to CTRL/R by printing the incomplete 
input line. It is typed by holding down the CTRL key and pressing R. 
CTRL/R echoes "R and is followed by a return and line feed. For 
example, at a hardcopy terminal you enter: 

MISTKAE © © © Etrur) 

The echoed result is: 

MISTKAE\EAK ~R 
MIST 



2.1.5.2 Line Erase (CTRL/U) - CTRL/U deletes the line being input, if 

typed before the line is terminated with the RETURN key. It is typed 

by holding down the CTRL key and pressing U. CTRL/U echoes as "U and 
is followed by a return and line feed. 



2.1.5.3 The RETURN Key - The RETURN key has the following effects, 
depending on how it is used: 

• When issued in place of an input file specification, the 
RETURN key causes EDI to terminate. 

• When issued in edit mode, the RETURN key causes the next line 
to be printed. That line becomes the current line. 

• When issued in input mode as the only character in an input 
line, the RETURN key causes a return to edit mode. 

• When issued alone after an INSERT command, the RETURN key 
invokes input mode. 



2.1.5.4 Terminating the Previous Text Line (ESCape or ALTmode) - When 
EDI is in edit mode, pressing the ESCape (or ALTmode) key causes the 
previous text line to be printed. That line becomes the current line. 
ESC can be used this way only in block mode, not in line-by-line mode. 

When EDI is in input mode, ESC acts as a return and terminates the 
line. If ESC is the first character of an input line, EDI exits from 
input mode. 
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2.1.5.5 Terminating EDI (CTRL/Z) - CTRL/Z causes EDI to terminate. 
EDI writes the remainder of the input file into the output file and 
then closes both files before terminating. Use CTRL/Z to terminate 
EDI in edit mode and input mode. CTRL/Z erases your last input line 
if you enter the command as a line terminator. 



2.1.6 EDI Command Conventions 

EDI uses asterisks (*) and ellipses (...) in special ways. The 
following sections describe these and also the notation convention 
used to define EDI command abbreviations. 



2.1.6.1 Use of Asterisk (*) - The asterisk (*) can be used in place 
of any numeric argument. It evaluates to 32767(10). 

Example 

The following command results in the printing of the remainder of 
the block buffer or file. 

PRINT * 



2.1.6.2 Use of Ellipsis (...) in Search Strings - In a number of the 
EDI commands, you must identify a string of characters to be located 
and/or changed. To reduce the necessary terminal entries, you can use 
the following special string constructs. In these special cases, the 
ellipsis (...) represents any number of intervening characters. 



Case 1. stringl. . .string2 

Case 2. . . .string 

Case 3. string... 

Case 4. ... 
Examples 



Any string that starts with stringl 
continues with any number of intervening 
characters and ends with the first 
occurrence of string2. 

Any string that starts at the beginning 
of the current line and ends with the 
first occurrence of string. 

The first string that starts with string 
and ends at the end of the current line. 

The entire current line. 



In the following examples, the CHANGE command is used with the 
four cases of special string constructs. In each case the 
current line reads: 

THIS IS A SAMPLE OF SPECIAL STRING CONSTRUCTS. 
Case 1. C /S A...E O/S AN EXAMPLE 

results in 

THIS IS AN EXAMPLE OF SPECIAL STRING CONSTRUCTS. 
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Case 2. 



C /...SPEC/HERE IS AN EXAMPLE OF SPEC 



results in 



HERE IS AN EXAMPLE OF SPECIAL STRING CONSTRUCTS. 



Case 3. 



C /STRING. . ./EDI STRING CONSTRUCTS. 



results in 



HERE IS A SAMPLE OF SPECIAL EDI STRING CONSTRUCTS. 



Case 4. 



C /.../EXAMPLES OF SPECIAL EDI CONSTRUCTS. 



results in 



EXAMPLES OF SPECIAL EDI CONSTRUCTS. 



2.1.6.3 Command Abbreviations - EDI permits the use of truncated 
commands. Where these shorter forms are allowed, the command format 
specifications represent the shortest acceptable form in uppercase 
letters. The lowercase letters may be entered optionally. The 
following example shows the abbreviations allowed for the VERIFY 
command. The command format specification is: 



The following truncations are valid for the VERIFY command: 

V 

Ve 

Ver 

Veri 

Ver if 

Verify 



2.2 BASIC EDI COMMANDS 

The basic EDI commands listed in Table 2-3 allow you to create a file, 
to modify a file by adding, deleting, or changing its contents, and to 
exit after the desired operations have been completed. A more 
detailed description of each command follows the table. These 
commands are the most important EDI commands. As you become familiar 
with EDI operations, the additional commands listed in Section 2.3 and 
described in Section 2.4 will allow you to use all of EDl's 
capabil ities . 



Verify 
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Table 2-3 
Basic EDI Commands 



Command 


Command Format 


Description 


ADD 


Add string 


Append string to current line. 


ADD & PRINT 


AP string 


Append string to current line 
and print resulting line. 


BOTTOM 


Bottom 


Move the current line pointer 
to the bottom of the current 
block (in block mode) or to the 
bottom of the file (in 
line-by-line mode). 


CHANGE 


[n]Change /stringl/ 
string2 [/] 


Replace stringl with string2 
n times in the current line. 


Etrl/z) 


Type a Control Z 


Close files and terminate 
editing session. 


DELETE 


Delete [n] 
or 

Delete [-n] 


Delete current line and n-1 
lines if n is positive; delete 
n lines preceding current line 
if n is negative. [-n] 
operates in block mode only. 


DELETE & 
PRINT 


DP [n] or DP [-n] 


Same as DELETE, except new 
current line is printed. 


(ESC) 


Type the ESC (or ALT) 
key 


Print previous line, make it 
new current line and exit from 
input mode (block mode only) . 
Same as NP-1. 


EXIT 


EXit [filespec] 


Close files, rename output 
file, and terminate editing 
session. 


INSERT 


INsert [string] 


Enter the string immediately 
following the current line. If 
no string is specified, EDI 
enters input mode. 


LOCATE 


[n] Locate string 


Locate nth occurrence of 
string. In block mode, search 
stops at end of current block. 


NEXT 


Next [n] or 
Next [-n] 


Establish new current line n 
lines away from current line. 


NEXT & PRINT 


NP [n] or NP [-n] 


Establish and print new current 
1 ine . 


PRINT 


Pr int [n] 


Print current line and the next 
n-1 lines. The last printed 
line is the new current line. 



(continued on next page) 
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Table 2-3 (Cont.) 
Basic EDI Commands 



Command 


Command Format 


Description 


RENEW 


RENew[n] 


Write current block to output 
file and read new block n from 
input file (block mode only) . 


m 


Press the RETURN key 


Print the next line, make it 
new current line, exit from 
input mode. Same as NP+1. 


RETYPE 


Retype string 


Replace current line with 
string or delete current line 
if string is not given. 


TOP 


Top 


Move the current line pointer 
to the top of the current block 
(in block mode) or top of file 
(in line-by-line mode) . TOP 
creates a new version of the 
file each time it is invoked in 
line-by-line mode. 


TOP OF FILE 


TOF 


Return to top of input file and 
save all pages previously 
edited. TOF creates a new 
version of the file each time 
it is invoked. TOF reads in a 
new block after writing the 
previous block to the output 
file. 



2. 2. 1 ADD 

This command causes the specified string to be appended to the current 
1 ine . 

Format 

Add string 

Example 

The following command completes the line HAPPY DAYS ARE HERE 
*A AGAIN. 

Note that the space after the A is the command terminator. EDI 
will not insert the space into the line. If a space is to 
precede AGAIN., the command should be: 

A W © AGAIN. 
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2. 2. 2 ADD & PRINT 

This command performs the same function as the ADD command except that 
the new line is printed. 

Format 

AP string 
Example 

Using the same line used for the ADD command, the following 
command causes the new line to be printed as follows: 

*AP AGAIN. 

HAPPY DAYS ARE HERE AGAIN. 



2.2.3 BOTTOM 

This command moves the current line pointer to the beginning of the 
last line of the current block (in block mode) or to the beginning of 
the last line of the file (in line-by-line mode). In block mode, the 
only processing EDI performs is line pointer positioning. In 
line-by-line mode, all the lines are copied from the input file to the 
output file until EOF is reached. If VERIFY ON is specified, the last 
line of the file block is displayed. Note, however, that if you 
deleted the last line before you issued BOTTOM, the pointer will be 
located past the text, and thus the last line will not be printed. 
BOTTOM performs the same function as END (see Section 2.4.14). 

Format 

Bottom 

Example 

*V ON 
*B0 

THIS IS THE LAST LINE 

In this example, the current line pointer is moved to the bottom 
of the block buffer and the last line is printed. 



2.2.4 CHANGE 

This command searches for stringl in the current line and, if found, 
replaces it with string2. If stringl is given, but cannot be located 
in the current line, EDI prints [NO MATCH] and returns an asterisk 
prompt. If stringl is not given, string2 is inserted at the beginning 
of the line. If string2 is not given, stringl is deleted from the 
current line. 

The search for stringl begins at the beginning of the current line and 
proceeds across the line until a match is found. 
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The characters that delimit stringl and string2 are normally slashes 
(/) . However, any matching characters not contained in the specified 
string may be used. The first character following the command is the 
beginning delimiter, the next matching character ends the string. 
Thus, characters used as delimiters must not appear in the string 
itself. The closing delimiter is optional. 

If you precede the command with a number n, the first n occurrences of 
stringl are changed to string2. After each replacement of stringl 
with string2, scanning restarts at the first character in the line. 
This allows you to generate a string of characters as shown in the 
following example. 

If no match occurs, a [NO MATCH] message is displayed. 
Format 

[n]Change /str ingl/string2 [/] 
Example 

TO SEPERATE THE THOUGHTS, USE SEPERATE SENTENCES. 

2C/SEPE/SEPA/ 
TO SEPARATE THE THOUGHTS, USE SEPARATE SENTENCES. 



2.2.5 CTRL/Z 

Typing CTRL/Z (holding the CTRL key down while typing the letter Z) 
terminates the editing session. If an output file is open when CTRL/Z 
is typed, all remaining lines in the block buffer and the input file 
are transferred (in that order) into the output file, all files are 
closed, and EDI exits. These actions occur whether EDI is in edit or 
input mode. If EDI is prompting for another file specification when 
CTRL/Z is entered, all files are closed (including any open secondary 
input file), and EDI exits. If you enter CTRL/Z as an input line 
terminator, that line is erased. 



2.2.6 DELETE 

This command causes lines of text to be deleted in the following 
manner: 

• If n is given and is a positive number, the current line and 
n-1 following lines are deleted. The new current line is the 
line following the last deleted line. 

• If n is given and is a negative number, the current line is 
not deleted, but the specified number of lines that precede it 
are deleted. The line pointer remains unchanged. A negative 
value for n can be used only in block mode. 

• If n is not given, the current line is deleted, and the next 
line becomes the new current line. 
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Format 

Delete [n] 
or 

Delete [-n] 
Example 

To delete the previous five lines in the block buffer, type the 
following command: 

*D -5 



2. 2. 7 DELETE & PRINT 

This command performs the same function as the DELETE command except 
that the new current line is printed when all lines have been deleted. 

Format 

DP [n] 

or 
DP [-n] 

If n is not specified, +1 is assumed. A negative value for n can 
be used only in block mode. 

Example 

If the following lines are contained in a file: 

THIS IS LINE 1 
THIS IS LINE 2 
THIS IS LINE 3 
THIS IS LINE 4 

and the line pointer is at the first line, the following command 
obtains the results shown below it: 

*DP 2 

THIS IS LINE 3 



2.2.8 The ESCape Key 

This command prints the previous line in the block (block mode only). 
That line becomes the current line. Thus, you can back up through a 
block, one line at a time, by pressing a series of Escapes. Pressing 
ESCape is equivalent to typing NP-1 (NEXT & PRINT command). 



2.2.9 EXIT 

This command transfers all remaining lines in the block buffer and 
input file (in that order) into the output file, closes the files, and 
terminates the editing session. If a file specification is used, the 
output file is renamed to the specified file name. 
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Format 



EXit [filespec] 



Example 

The command 



*EX 



terminates the editing session without renaming the output file. 
It causes EDI to display: 



[EXIT] 



The output f ilename.f iletype is the same as the input 
f ilename.f iletype . The version number is one greater than that 
of the input file. 



2.2.10 INSERT 



This command inserts a string immediately following the current line. 
The string becomes the new current line. If a string is not 
specified, EDI enters input mode. 



Format 



Insert [string] 



Example 

*I TEXT INSERT IN EDIT MODE Insert a line of text 

immediately after the current 
1 ine . 



*I 

TEXT INSERT 1 IN INPUT MODE 
TEXT INSERT 2 IN INPUT MODE 
ETC. 



An I followed by a RETURN 
causes EDI to switch to input 
mode. A series of new lines 
may be input following the 
current line. 



A RETURN or ESC as the only 
character in an input line 
causes EDI to return to edit 
mode and to prompt for a new 
command . 



2.2.11 LOCATE 



This command causes a search for a string, beginning at the line 
following the current line. The string may occur anywhere in the line 
sought. The line pointer is positioned to the line containing the 
match. When the line is located, it is printed if VERIFY ON is in 
effect . 



If a string is not specified, the line following the current line is 
considered a match, and the line pointer is positioned there. If n is 
specified, the nth occurrence of string is located. 
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LOCATE applies to the block buffer if EDI is in block mode and to the 
input file if in line-by-line mode. 

Format 

[n]Locate [string] 
Example 

The following command can be used to locate the line HAPPY DAYS 
ARE HERE AGAIN. 

*L PPY 

EDI searches the file or block buffer and if VERIFY ON is 
specified prints the line when it is located. The current line 
pointer is set to the located line. 



2.2.12 NEXT 

This command moves the current line pointer backward and forward in 
the file. A positive number moves the current line pointer n lines 
beyond the current line. A negative number moves the current line 
pointer backward n lines. 

Format 

Next [n] 
or 

Next [-n] 

If n is not specified, a value of +1 is assumed. A negative for 
n can be used only in the block mode. 

Example 

In block mode, the following command moves the current line 
pointer back five lines: 

*N -5 



2. 2. 13 NEXT & PRINT 

This command has the same effect as the NEXT command except that the 
new current line is printed. 

Format 

NP [n] 

or 
NP [-n] 

The following conventions can be used in place of issuing an NP 
command : 

• Pressing the RETURN key is the same as an NP+1 command. 

• Pressing the ESCape (or ALTmode) key while in the block mode 
is the same as an NP-1 command. 

• If n is not specified, then a value of +1 is assumed. 
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Example 

Assume the following four lines are contained in the file and the 
line pointer is at the first line. 

LINE 1 OP THE FILE 

LINE 2 OF THE FILE 

LINE 3 OF THE FILE 

LINE 4 OF THE FILE 

If the following command is issued, EDI returns the following 
printout: 

*NP 2 



LINE 


3 


OF 


THE 


FILE 


* (RET) 










LINE 


4 


OF 


THE 


FILE 


* (ESC) 










LINE 


3 


OF 


THE 


FILE 


* m 










LINE 


2 


OF 


THE 


FILE 



2.2.14 PRINT 

This command prints the current line and the next n-1 lines on the 
terminal. The last line printed becomes the new current line. If it 
is not specified, a value of 1 is assumed. 

Format 

Print [n] 
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Example 

Example 2-1 illustrates both the PRINT and the TYPE commands: 



Example 2-1 Line Pointer Position for the 
TYPE Command and the PRINT Command 

Before 



O 



File 


A 




File 


E 


Line 


1 


o 


Line 


1 


Line 


2 


Line 


2 


Line 


3 




Line 


3 


Line 


4 




Line 


4 


Line 


5 




Line 


5 



*TYPE 5 



Line 


1 


Line 


2 


Line 


3 


Line 


4 


Line 


5 



* 



*PRINT 5 



Line 


1 


Line 


2 


Line 


3 


Line 


4 


Line 


5 



* 



After 



File A 



o 



Line 


1 


Line 


2 


Line 


3 


Line 


4 


Line 


5 



[ ^> is the Line Pointer 



File B 



Line 


1 


Line 


2 


Line 


3 


Line 


4 


Line 


5 


ZK-173-81 
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2.2.15 RENEW 

This command writes the current block buffer into the output file and 
reads a new block from the input file. The optional value n is a 
repetition count: if you specify n, the process is repeated n times. 
The intermediate blocks are written into the output file and the last 
block is left in the block buffer. If n is not specified, a single 
RENEW process is performed. This command may be used only in block 
mode. Refer to Section 2.1.3 for information on how EDI block buffers 
are processed. 

Format 

RENew [n] 
Example 

*RENEW 10 

Ten blocks are transferred consecutively from the input file to 
the block buffer. The initial contents of the block buffer and 
the next nine blocks are transferred consecutively to the output 
file. The current line pointer points to the first line in the 
tenth block, which is currently in the block buffer. 



2. 2. 16 The RETURN Key 

In edit mode, this command prints the next line in the file or block 

buffer. That line becomes the current line. Thus, you can scan 

through a file or block, one line at a time, by pressing a series of 

RETURNS. This command is equivalent to NP+1 (NEXT & PRINT command). 

In input mode, a RETURN causes EDI to return from input mode to edit 
mode. 



2.2.17 RETYPE 

This command replaces the current line with a string. If a string is 
not specified, the line is deleted. 

Format 

Retype [string] 
Example 

*R THIS IS A NEW LINE 
The string THIS IS A NEW LINE replaces the current line. 



2.2.18 TOF 

This command creates a new version of the file and returns the current 
line pointer to the first line of the file. TOF processing copies the 
input file into the output file, closes both, then opens the latest 
version of the file as the input file. If you issue this command when 
in line-by-line mode, EDI switches to block mode after saving the 
edited data. The first block is read into the block buffer. 
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Format 

TOF 
Example 

*TOF 

This command writes the previously edited pages into the output 
file, resets the current line pointer to the top of the input 
file, and reads the first block into the block buffer. 



2.2.19 TOP 

This command sets the current line pointer to the top of the current 
block (in block mode) or to the top of the file (in line-by-line 
mode). When the current line pointer is positioned with TOP, you can 
enter lines preceding the first line in the block or file. 

TOP differs from TOF in the following ways: 

• In line-by-line mode, TOP creates a new file and moves the 
current line pointer to the top of the file. Unlike TOF, it 
does not cause EDI to return to block mode. 

• In block mode, TOP moves the current line pointer to the top 
of the current block and does not create a new output file. 
TOF moves the current line pointer to the top of the file and 
creates a new output file. 

Format 

Top 
Example 

*TOP 

This command directs the current line pointer to the top of the 
current block in block mode. 



2.3 EDI COMMANDS: FUNCTION SUMMARY 

EDI commands can be arranged by functional similarity. For example, 
all the commands you use to locate a string can be grouped under the 
function heading "Locator Commands." This section contains summaries 
of the following command categories: 

• Setup commands select operating conditions, close and open 
files, and select data modes. 

• Locator commands control the position of the current line 
pointer and thus determine which text line is acted upon. 

• Text modification commands change text lines. 

• Macro commands define, store, recall, and use sequences of EDI 
commands. 
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• File input/output commands transfer text to and from 
input/output, and save files. 

• Device output commands send output to a terminal or line 
printer . 

• Close and exit commands terminate editing operations. 



2.3.1 Setup Commands 

The setup commands allow you to enable or disable certain special 
features of EDI. Among these features are the block and line-by-line 
text access modes, and the automatic verification of LOCATE commands. 
Setup commands are listed in Table 2-4. 



Table 2-4 
EDI Setup Commands 



Command 


Format 


Description 


BLOCK ON/OFF 


BLock [ON] or 
BLock OFF 


Switch text access modes. 


CONCATENATION 
CHARACTER 


CC [letter] 


Change concatenation character 
to specified character (default 
is &) . 


OPEN SECONDARY 


OPens filespec 


Open specified secondary file. 


OUTPUT ON/OFF 


output ON or 
Output OFF 


Continue or discontinue 
transfer to output file 
(line-by-line mode). 


SELECT PRIMARY 


SP 


Reestablish primary file as 
input file. 


SELECT SECONDARY 


SS 


Select opened secondary file as 
input file. 


SIZE 


SIZE n 


Specify maximum number of lines 
to be read into block buffer. 


TAB 


TAb [ON] or 
TAb OFF 


Turn automatic tabbing on or 
off. 


UPPER CASE 
ON /OFF 


UC [ON] or 
UC OFF 


Enable or disable conversion of 
lowercase characters entered 
from terminal to uppercase 
characters. 


VERIFY ON/OFF 


Verify [ON] or 
Verify OFF 


Select whether locator and 
change commands are verified. 
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2.3.2 Locator Commands (Line-Pointer Control) 

During editing operations, EDI maintains a pointer that identifies the 
current line (that is, the line to which any subsequent editing 
operations refer). Commands that modify the line pointer's location 
are called locator commands. These commands are listed in Table 2-5. 

The locator commands allow you to: 

• Set the line pointer to either the top or bottom of the input 
file or block buffer. 

• Move the line pointer a specified number of lines away from 
its current position. 

• Move the line pointer to a line containing a given text 
string . 

In edit mode, the RETURN and ESCape (or ALTmode) keys act to relocate 
the line pointer. A RETURN moves the pointer to the next line. An 
ESCape moves the line pointer back one line (in block mode only). In 
each case, the line is printed. 

If VERIFY ON is in effect, the located line is printed after a BOTTOM, 
END, FIND, PAGE FIND, PAGE LOCATE, or SEARCH & CHANGE command. 



Table 2-5 
EDI Locator Commands 



Command 


Format 


Description 


BEGIN or 
TOP 


Beg in 
Top 


Set current line to the line 
preceding top line in file 
(line-by-line mode) or block 
buffer (block mode) . Both 
commands create copies of the 
file each time they are invoked 
in line-by-line mode. The 
commands are equivalent. 


BOTTOM or 
END 


BOttom 
End 


Set current line to last line 
in file or block buffer. The 
commands are equivalent. 


(or ALTmode) 


Press ESC (or ALT) 
key 


Print previous line, make it 
new current line, or exit from 
input mode (Block mode only.) 


FIND 


[n]Find tstring] 


Search current block or input 
file, beginning at line 
following current line for the 
nth • occurrence of string. 
String must begin in column 1. 
Set line pointer to located 
1 ine . 


LOCATE 


[n] Locate string 


Locate nth occurrence of 
string. In block mode, search 
stops at end of block. 



(continued on next page) 
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Table 2-5 (Cont.) 
EDI Locator Commands 



Command 


Format 


Description 


NEXT 


Next [n] 
Next [-n] 


Establish new current line n 
lines away from current line. 


NEXT & PRINT 


NP [n] or NP [-n] 


Establish and print new current 
1 ine . 


(Block 
Mode only) 


rAue n 


Ciil Let DIOCK ulOuct neau page n 

into block buffer. If n is less 
than current page number, do 
TOF first. Pages are delimited 
by form feed characters. 


PAGE FIND 
(Block 
Mode only) 


[n]PFind string 


Search successive blocks for 
the nth occurrence of string. 
String must start in column 1. 


PAGE LOCATE 
(Block 
Mode only) 


[n] PLocate string 


Search successive blocks for 
the nth occurrence of string. 
String may occur anywhere in 
1 ine . 


(RET) 


Press RETURN Key 


Print the next line, make it 
the current line, exit from 
input mode. 


SEARCH & 
CHANGE 


SC /stringl/string2 [/] 


Locate stringl and replace it 
with string2. 



2.3.3 Text Modification and Manipulation Commands 

The text modification and manipulation commands enable you to modify 
text. Table 2-6 lists these commands. 



Table 2-6 

EDI Text Modification and Manipulation Commands 



Command 


Format 


Description 


ADD 

ADD & PRINT 
CHANGE 


Add string 
AP string 

[n] Change/stringl/ 
str ing2 [/] 


Append string to current 
1 ine . 

Append string to the 
current line and print 
resulting line. 

Replace stringl with 
string2 in the current 
line n times. 



(continued on next page) 
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Table 2-6 (Cont.) 
EDI Text Modification and Manipulation Commands 



Command 



Format 



Description 



DELETE 



Delete [n] or 
Delete [-n] 



DELETE & PRINT 



ERASE 



DP [n] or DP [-n] 



ERASE [n] 



FORM FEED 



INSERT 



LINE CHANGE 



OVERLAY 



FF 



Insert string 



[n] LC/stringl/ 
string2 [/] 



Overlay [n] 



PASTE 



RETYPE 



TOP OF FILE 



UN SAVE 



PAste/string 1/ 
string2 [/] 



Retype [string] 



TOF 



UNSave [filespec] 



Delete current line and 
n-1 lines if n is 
positive; delete n lines 
preceding current line if 
n is negative. [-n] 
operates in block mode 
only. 

Same as DELETE except new 
current line is printed. 

Erase the current line if 
in line-by-line mode. 

Erase the current block 
buffer and the next n-1 
blocks if in block mode. 

Insert form feed into 
block buffer (used to 
del imit a page) . 

Enter string following 
current line or enter 
input mode if string is 
not specified. 

Change all occurrences of 
stringl in current line 
(and n-1 lines) to 
string2. 

Delete n lines, enter 
input mode, and insert 
new line(s) as typed in 
place of original 

1 ine (s) . 

Search all remaining 
lines in file or block 
buffer for stringl and 
replace with string2. 

Replace the current line 
with string or delete the 
current line if string is 
not given. 

Return to the top of the 
input file and save all 
pages previously edited. 

Insert all lines from 
specified file following 
current line. If filespec 
is not given, SAVE.TMP is 
used . 
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2.3.4 Macro Commands 

These commands allow you to define, store, recall, and use macros. A 
macro is a series of EDI commands that, once defined, can be executed 
repeatedly. Table 2-7 lists the macro commands. 



Table 2-7 
EDI Macro Commands 





ro L luau 




MACRO 


MACRO x definition 


Define macro number x. The 
value x may be 1, 2, or 3. 


MACRO CALL 


MCall 


Retrieve macro definitions 
stored in file MCALL ;n . 


MACRO EXECUTE 


[n]Mx [a] 


Execute macro x [n] times, 
while passing numeric 
argument [a] . 


MACRO 
IMMEDIATE 


[n] <definition> 


Define and execute a macro n 
times. Store it as macro 
number 1. 



2.3.5 File Input/Output Commands 

Input/output commands control the movement of text to and from 
input/output files, and save files. Table 2-8 lists these commands. 



Table 2-8 
EDI Input/Output Commands 



Command 


Format 


Description 


FILE 


FILe filespec 


Transfer lines from input file 
to both the output file and the 
specified file until a form 
feed or end-of-file is 
encountered. (Line-by-line 
mode only.) 


READ 


REAd [n] 


Read next n blocks of text into 
block buffer. If buffer 
contains text, new text is 
appended to it. 


RENEW 


RENew [n] 


Write the current block to the 
output file and read new block 
from the input file. 



(continued on next page) 
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Table 2-8 (Cont.) 
EDI Input/Output Commands 



Command 


Fo rmat 


Description 


SAVE 


SAve 


[n] [filespec] 


Save current line and the next 
n-1 lines in the specified 
file. If filespec is not 
given, lines are saved in file 
SAVE.TMP. SAVE puts the 
temporary file in the UFD on 
the device for the file you are 
editing. You can override the 
default by specifying a 
different device and UFD. 


WRITE 


Write 




Write contents of block buffer 
to output file and erase block 
buffer . 


2.3.6 Device 


Output 


Commands 





These commands direct output to your terminal or to a pseudo device 
(CL: ) . They are listed in Table 2-9. 



Table 2-9 
EDI Device Output Commands 



Command 


Format 


Description 


LIST ON TERMINAL 


List 


Print on the terminal all lines 
remaining in block buffer (block 
mode) or input file 
(line-by-line mode), beginning 
at current line. 


LIST ON PSEUDO- 
DEVICE 


LP 


Same as LI, except that printing 
is performed on the pseudo 
device CL: . 


PRINT 


Print [n] 


Print the current line and the 
next n-1 lines. The last 
printed line is the new current 
1 ine . 


TYPE 


TYpe [n] 


Print next n lines. In 
line-by-line mode, identical to 
PRINT command. In block mode, 
line pointer remains at current 
line unless end-of-block was 
reached . 
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2.3.7 CLOSE and EXIT Commands 

The CLOSE and EXIT commands terminate EDI operations and write the 
remainder of the input file into output file. Table 2-10 lists these 
commands. 



Table 2-10 
EDI Close Operation Commands 



Command 


Format 


Description 


CLOSE 


CLose [filespec] 


Transfer remaining lines in 
block buffer and input file to 
output file and close files. 
If file specification is used, 
output file is renamed. EDI> 
prompt is issued. 


CLOSE SECONDARY 


CLOSES 


Close secondary file. 


CLOSE & DELETE 


CD1 [filespec] 


Same as CLOSE except that input 
file is deleted. EDI> prompt 
is issued. 


jCTRL/Z) 


Type a control Z 


Close files and terminate EDI. 


EXIT 


EXit [filespec] 


Close files, rename output 
file, and terminate EDI. 


EXIT & DELETE 


EDx [filespec] 


Transfer remaining lines in 
block buffer and input file to 
output file and close file. 
Rename file if file 
specification is given. Delete 
input file and terminate EDI. 


KILL 


KILL 


Close input and output files, 
delete output file. EDI> 
prompt is issued. 



2.4 EDI COMMANDS: DETAILED REFERENCE SUMMARY 

This section lists each EDI command in alphabetical order. Each 
command description comprises the function of the command and the 
command format. Most descriptions include examples and usage 
information. The exceptions are the basic commands, which are 
described in detail in the preceding section. In this section, only 
the function and format of basic commands are described. 



2.4.1 ADD 

ADD causes the specified string to be appended to the current line. 
Format 

Add string 

For examples and information describing how to use ADD, refer to 
Section 2.2.1. 
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2. 4. 2 ADD & PRINT (AP) 

ADD & PRINT performs the same function as ADD except that the new line 
is printed. 

Format 

AP string 

For examples and information describing how to use ADD & PRINT, refer 
to Section 2.2.2. 



2.4.3 BEGIN 

BEGIN sets the current line pointer to the beginning of the file in 
line-by-line mode, or to the beginning of the block buffer in block 
mode. The current line is one line preceding the top line in the file 
or block buffer. Thus, you can insert text at the beginning of a file 
or block. 

If EDI is in line-by-line mode, BEGIN copies the input file into the 
output file, closes both, then opens the latest version of the file. 
BEGIN performs the same function as TOP. 

Format 

Begin 

Example 

*B 

In this example, the current line pointer is moved to the top of 
the block buffer (block mode is assumed) . 



2. 4. 4 BLOCK ON/OFF 

This command allows you to switch between block mode and line-by-line 
mode. When you enter BLOCK ON, block mode becomes active and the next 
block of text is brought into the block buffer. When you enter BLOCK 
OFF, the current block being processed is written to the output file 
and line-by-line mode becomes active. The first line from the next 
sequential block in the input file becomes the current line. 

If you enter an unnecessary BLOCK command (for example, BLOCK ON when 
EDI is already in block mode), the command is ignored. 

BLOCK ON is the default text access mode. It is assumed when neither 
ON nor OFF is specified. 

Format 

BLock [ON] 
or 

BLock OFF 
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Example 

★BLOCK ON 

This command causes EDI to switch to block mode. The next block 
of text is read into the block buffer. 



2.4.5 BOTTOM 

BOTTOM sets the current line pointer to the beginning of the last line 
of the block (in block mode) or of the input file (in line-by-line 
mode) . 

Format 

BOttom 

For examples and information on how to use BOTTOM, refer to Section 
2. 2. 3. 



2.4.6 CHANGE 

CHANGE searches for stringl in the current line and, if found, 
replaces it with string2. 

Format 

[n] Change /str ingl/string2 [/] 

For examples and information on how to use CHANGE, refer to Section 
2. 2. 4. 



2.4.7 CLOSE 

This command transfers all remaining lines in the block buffer and 
input file (in that order) into the output file and closes both files. 
If a file specification is included, the output file is renamed to the 
file spec. EDI then returns to its initial command sequence, prompts 
with EDI>, and waits for you to type another file specification. 

If a secondary file was opened during the editing session and was not 
closed, it remains open. 

Format 

CLose [filespec] 
Example 

*CL 
EDI> 

This command closes both input and output files, and EDI returns 
to the initial command sequence. 
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contains an ampersand. 

must be changed to a 
the line. 

concatenation 



2.4.8 CLOSE SECONDARY (CLOSES) 

Use this command when you have finished extracting text from a 
secondary input file. You must enter CLOSES before you can use 
another secondary file as input. 

Format 

CLOSES 



2.4.9 CLOSE & DELETE (CD) 

all remaining lines in the block buffer and the 
order) into the output file, and closes both 
is then deleted. If a file specification is 
file is renamed to the file spec. This command 
that the input file is deleted. 

If a secondary file was opened during the editing session and was not 
closed, it remains open. 

Format 

CD1 [filespec] 



2.4.10 CONCATENATION CHARACTER (CC) 

The concatenation character allows you to give commands on one input 
line. By default, the concatenation character is the ampersand (&) . 
To reference text containing an ampersand (for example, in LOCATE or 
CHANGE commands) , you must change the concatenation character to some 
other character. 

If the CC command is used without an argument, the concatenation 
character is changed to the ampersand. 



2.4.10 CONCATENATION CHARACTER (CC) 

The concatenation character allows you to give 
line. By default, the concatenation charact 
To reference text containing an ampersand (for 
CHANGE commands) , you must change the concate 
other character. 

If the CC command is used without an argum 
character is changed to the ampersand. 

Format 

CC [letter] 



Example 



*CC : 

*L A&B:C /A&B/ABC/ 

CONCATENATION TEST CONTAINING A&B. 
CONCATENATION TEST CONTAINING ABC. 
*CC 

In this example, the string to be located 
Therefore, the concatenation character 
different character before EDI can locate 

The first command line changes the default 
character from the ampersand to the colon. 
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The second command line instructs EDI to locate the string A&B 
and change that string A&B to ABC. (Note: this line contains 
two commands that are concatenated by the new concatenation 
character, the colon.) 

The third command line changes the concatenation character back 
to the normal default value, &. 



2.4.11 CTRL/Z 

CTRL/Z is a Command Line Interpreter (CLI) function that terminates 
EDI. For usage information on CTRL/Z, refer to Section 2.2.5. 



2.4.12 DELETE 

DELETE deletes a specified number of lines from a file. 
Format 

Delete n 

For examples and information on how to use DELETE, refer to Section 
2 • 2.6. 



2.4.13 DELETE & PRINT (DP) 

DELETE & PRINT performs the same function as DELETE, except that it 
displays the new current line after the specified lines are deleted. 

Format 

DP n 

For examples and information on how to use DELETE & PRINT, refer to 
Section 2. 2. 7. 



2.4.14 END 

END sets the current line pointer to the beginning of the last line of 
the block or input file. If EDI is in block mode, only line pointer 
positioning occurs. In line-by-line mode, all lines are copied from 
the input file to the output file until EOF is reached. The last line 
in the block or file is displayed if VERIFY ON is in effect. Note, 
however, that if the last line was deleted before you issued END, the 
pointer will be located past the text, and thus the last line will not 
be printed. END performs the same function as BOTTOM. 

Format 

End 
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Example 

*V ON 
*END 

THIS IS THE LAST LINE 

This command moves the current line pointer to the bottom of the 
block buffer (block mode is assumed) . 



2.4.15 ERASE 

In line-by-line mode, this command erases the current line. In this 
mode, n can only be 1. In block mode, this command erases the current 
block buffer and the next n-1 blocks. If n is not specified, +1 is 
assumed . 

Format 

ERASE [n] 
Example 

*ERASE 5 

This command causes the contents of the current block buffer and 
the next 4 blocks to be erased. These blocks are not written 
into the output file. 



2.4.16 The ESCape Key 

This command prints the previous line in the block (block mode only). 
That line becomes the current line. Thus, you can back up through a 
block, one line at a time, by pressing a series of Escapes. Pressing 
ESCape is equivalent to typing NP-1 (NEXT & PRINT command). 

If EDI is in input mode, ESC acts like RETURN and terminates a line of 
input. ESC also exits from input mode if it is the first character of 
the line. 



2.4.17 EXIT 

EXIT writes all remaining records to the output file, closes the 
files, and terminates EDI. 

Format 

EXIT [filespec] 

For examples and information on how to use EXIT, refer to Section 
2. 2. 9. 



2.4.18 EXIT & DELETE (ED) 

This command functions in the same way as the CLOSE & DELETE command 
except that EDI also terminates. 
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Format 

EE* [filespec] 
Example 

*EDX NEWFILE.DOC 

[EXIT] 

> 



2.4.19 PILE 

This command — legal in line-by-line mode only — transfers lines from 
the input file to both the output file and a specified file, beginning 
with the current line, until a form feed character is encountered as 
the first character in a line or until end-of-file is reached. At 
that time, the specified file is closed. The form feed character is 
not included in the specified file. During the transfer, the original 
file remains intact (that is, all lines written to the specified file 
are also written to the normal output file, including the form feed). 
When the command is complete, the current line in the input file is 
one line beyond the form feed. 

BLOCK OFF must be in effect for FILE to work properly. 

If the specified file does not already exist, a new file is created. 
If the specified file does exist, the latest version of the file 
contains the new data. 

Format 

FILe filespec 
Example 

*FIL SEC. DAT 

EDI writes the contents of the input file, from the current line 
to the end, into both the output file and the file SEC. DAT. 



2.4.20 FIND 

This command searches the block buffer or input file for a string, 
beginning at the line following the current line. The string must 
begin in column 1 of the line matched. The line pointer is positioned 
at the line containing the match. When the line containing the string 
is found, it is printed if VERIFY ON is in effect. 

FIND applies to the block buffer if EDI is in block mode and to the 
input file if EDI is in line-by-line mode. 

If a string is not specified, the line following the current line is 
considered a match. If n is specified, the nth occurrence of the 
string is found. 

Format 

[n]Find [string] 
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Example 

*V ON 
*F LOOK 

LOOK AT THE FIRST CHARACTER IN THE LINE. 

In this example, EDI searches the block buffer (or file) for a 
line that begins with LOOK and prints the line when it is found. 



2. 4. 21 FORM FEED (FF) 

This command allows you to insert form feeds into the text to delimit 
pages. The form feed is inserted after the current line. The line 
containing the form feed then becomes the new current line. 

Format 

FF 

Example 

*P 

THIS IS THE LAST LINE ON THE PAGE 
*FF 

In this example, a form feed is inserted into the text following 
the current line. 



2.4.22 INSERT 

INSERT inserts a string immediately following the current line. The 
string becomes the current line. 

Format 

Insert [string] 

For examples and information on how to use INSERT, refer to Section 
2. 2. 10. 



2.4.23 KILL 

This command returns EDI to the initial command sequence without 
retaining the output file. When this command is executed, the input 
file is closed and the output file is deleted. 

Format 

KILL 

Example 

*KILL 
EDI> 
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In this example, the output file is deleted and EDI displays the 
prompt : 

EDI> 

At this point, you can return control to your CLI by means of 
CTRL/Z or enter a file specification for a file to be edited. 



2.4.24 LIME CHANGE (LC) 

This command is similar to CHANGE except that all occurrences of 
stringl in the current line are changed to string2. A numeric value n 
preceding the command changes the current line and the next n-1 lines. 
If string2 is not given, all occurrences of stringl are deleted. New 
lines are printed if the VERIFY ON command is in effect. 

If stringl is given, but EDI cannot locate the string in the current 
line, EDI prints [NO MATCH] and returns the asterisk prompt. 

Format 

[n]LC /stringl/string2 [/] 

Example 

If the current line is: 

THES ES THE LINE TO BE ESSUED. 

The following commands would correct the errors: 

*V ON 

*LC /ES/IS 

THIS IS THE LINE TO BE ISSUED 



2.4.25 LIST ON TERMINAL (LI) 

This command prints on your terminal all remaining lines in the block 
buffer (block mode) or all remaining lines in the input file 
(line-by-line mode), beginning at the current line. At the end of the 
listing, the current line pointer is repositioned to the top of the 
input file or block buffer. 

If terminal host synchronization is installed at system generation, 
you can control printing functions using CTRL/0, CTRL/S, and CTRL/Q. 
To suppress printing at any point, type CTRL/0. Printing can be 
suspended temporarily with CTRL/S and resumed with CTRL/Q. 

Format 

List 

Example 

*LI 

This command causes all remaining lines in the block buffer or 
all remaining lines in the input file to be printed on the 
terminal . 
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2.4.26 LIST ON PSEUDO DEVICE (LP) 

This command functions in the same manner as the LIST ON TERMINAL 
command except that the remaining lines in the block buffer (block 
mode) or the remaining lines of the input file (line-by-line mode) are 
listed on the pseudo device CL: . In most systems, CL: is set to the 
system line printer. 

Format 

LP 

Example 

*LP 

This command causes all remaining lines in the block buffer or 
all remaining lines in the input file to be printed on the pseudo 
device CL: . 



2.4.27 LOCATE 

LOCATE searches for a string beginning at the line following the 
current line. The string can occur anywhere in the lines searched. 

Format 

[n] Locate string 

For examples and information on how to use LOCATE, refer to Section 
2. 2. 11. 



2.4.28 MACRO 

This command is used to define macros. Space is available for three 

macro definitions. The definition can be any legal EDI command or 

string of legal EDI commands connected by the concatenation character. 

If a numeric argument is to be passed to the macro at execution time, 
a percent sign (%) must be inserted in the macro definition at the 
point where the numeric argument is to be substituted. Then the value 
passed with the MACRO EXECUTE command replaces the percent sign when 
the macro is executed. 

A MACRO definition may contain more than one percent sign. If it 
does, the single numeric value given in a MACRO EXECUTE command 
replaces each percent sign. However, a macro may not have two or more 
independent arguments. 

Format 

MACRO x definition 



x 



Specifies the macro number (1, 2, or 3). 
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Examples 

To find the nth occurrence of the string ABC in the current block 
and replace that occurrence and all remaining occurrences within 
the block with the string DEF, the following macro could be used: 

♦MACRO 1 %L ABC&PA /ABC/DEF 

The following command executes the macro and searches for the 
tenth and succeeding occurrences of ABC. 

*M 1 10 



The following macro definition and subsequent invocation could be 
used to change all occurrences of the strings ABC and GHI to DEF 
and JKL, respectively. The substitution is made in the current 
block and the next four blocks (five blocks in all) . 

*MACRO 1 PA /ABC/DEF/ &PA /GHI/JKL/&RENEW (MACRO command) 

*5M 1 (MACRO EXECUTE command) 



2.4.29 MACRO CALL (MC) 

This command allows you to retrieve up to three macro definitions 
previously stored in a file. The macro definitions must contain only 
the "definition" portion of the MACRO command. The macro definitions 
are stored in successively numbered macros: the first definition 
becomes macro 1, and so on. 

The file used to store the macro definitions must be the latest 
version of file MCALL — that is, MCALL ;n . The file type must be null 
or blank. If the macro definitions to be loaded are in a file of 
another name, you can use PIP with the /NV switch, to rename the file. 
(Refer to Chapter 3 for descriptions of PIP commands.) 

Format 

MCall 

Strings of concatenated EDI commands can be written as EDI macro 
definitions, and up to three EDI macro definitions can be stored 
in file MCALL;n. The MC command is used to call the latest 
version of file MCALL and move the three definitions into the 
macro storage area. Then you can execute the desired macro 
without having to type the complete command. 

Macro calls may not be nested. 

The concatenation character may precede, but not follow, a macro 
call. 

Example 

*MC 

This command retrieves the macro definitions stored in file 
MCALL ;n , where n represents the latest version of the file MCALL. 
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2.4.30 MACRO EXECUTE 

This command executes a macro n times while passing it an optional 
numeric argument a. If a macro numeric argument is defined with the 
percent sign (%) in the macro definition, the numeric argument 
contained in this command is passed for each execution of the macro. 
Before a macro can be executed, it must either have been defined by 
means of a MACRO command or called with a MACRO CALL command. 

Use the MACRO EXECUTE command to execute any one of the three macro 
definitions stored in the EDI macro storage area any number of times. 

Format 

[n]Mx [a] 



Specifies the number of times the macro is to be 
executed . 



Specifies the macro number (1, 2, or 3). 



Specifies the numeric argument to be passed when the 
macro is executed (ignored if the argument % is not 
present in macro definition) . 

Examples 

*2M1 



Execute macro number 1 twice. 



*3M2 5 

Execute macro number 2 three times, passing the numeric argument 
5 each time the macro is executed. 

The example in Section 2.6.4 illustrates how to use the EDI macro 
commands in editing a file. 



2.4.31 MACRO IMMEDIATE 

This command defines and executes a macro in one step. The definition 
is enclosed within angle brackets and is identical to that of the 
MACRO command. The definition is copied into the macro 1 storage area 
and immediately executed n times. The macro may also be subsequently 
executed by entering an Ml command. The command is equivalent to the 
two macro commands: 

MACRO 1 definition 
nMl 

Format 

n<def ini tion> 
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Example 

*<L ABC&C /ABC/DEF> 

This command causes EDI to search the current block buffer for 
the string ABC and, when it locates ABC, to change the string to 
DEF. This macro is stored as macro number 1. 

The example in Section 2.6.3 illustrates the use of the MACRO 
IMMEDIATE command. 



2.4.32 NEXT 

NEXT moves the current line pointer backward and forward in the file. 
A positive number moves the current line pointer forward, a negative 
current line number moves it backward. 

Format 

Next [n] 
or 

Next [-n] 

For examples and information on how to use NEXT, refer to Section 
2. 2. 12. 



2. 4. 33 NEXT & PRINT 

NEXT & PRINT performs the same function NEXT performs except that the 
new current line is displayed. 

Format 

NP [n] 
or 
NP [-n] 

For examples and information on how to use NEXT & PRINT, refer to 
Section 2.2.13. 



2.4.34 OPEN SECONDARY 

This command opens the specified secondary input file. The primary 
input file, if any, remains open. Subsequent text is read from the 
primary input file until the secondary input file is selected by means 
of the SELECT SECONDARY command (SS) for input. 

Format 

OPens filespec 

Example 

★OPENS RICKS. MAC 
*SS 

★READ 1 

The file RICKS. MAC is opened as a secondary input file, then the 
first block is read in. 
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2.4.35 OUTPUT ON/OFF 

This command, used only in the line-by-line mode, allows you to 
continue or discontinue the transfer of text to the output file. 
OUTPUT ON is the default condition. It is automatically reestablished 
each time a CLOSE command is issued. 

Format 

OUtput ON 
or 

OUtput OFF 

If neither ON or OFF is specified, ON is assumed. 
Example 

♦BLOCK OFF 
* OUT PUT OFF 
*N 5 

*OUTPUT ON 

This example shows how to bypass five lines of text in the input 
file so that these lines are not written into the output file. 

The first command sets line-by-line mode. 

The second command disables the transfer of text to the output 
file. 

The third command bypasses five consecutive lines of text from 
the input file. 

The fourth command reenables the transfer of text to the output 
file. 



2.4.36 OVERLAY 

This command deletes n lines and replaces them with any number of 
lines that you type. If n is not specified, the current line is 
deleted and replaced with the lines typed. When you enter the OVERLAY 
command, EDI enters input mode. All text that you type goes into the 
file until you enter a carriage return as the only character in an 
input line. 

Format 

Overlay [n] 
Example 

*0 2 

This command deletes two lines and causes EDI to enter input 
mode . 
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2.4.37 PAGE 

This command causes EDI to enter block mode, if not already in it, and 
read page n into the block buffer.. A page is delimited by form feeds. 
If n is less than the current page number, a TOF command is performed 
first. TOF processing writes the input file to the output file, 
closes both files, then opens the latest version of the file. 

If n is greater than the current page number, the necessary number of 
RENEW commands is executed to read page n into the block buffer. 

Format 

PAGe n 

Example 

*PAG 1 

[00050 LINES 

[00050 LINES 

[00050 LINES 

[00050 LINES 

[00017 LINES 

[PAGE 1] 
* 

This example shows a quick way to get to the last block in a file 
that contains no form feed page delimiters. EDI's page count is 
not incremented unless it encounters form feed characters or an 
end-of-file mark. Thus, in a file without form feeds (that is, 
most files) , EDI renews the block buffer until it encounters an 
end-of-file mark. Note that the final block contains 17 lines of 
text. 



2. 4. 38 PAGE FIND 

This command performs the same function as the FIND command except 
that successive blocks are searched until the nth occurrence of the 
string has been found. The contents of the block buffer and the 
blocks between the current block and the block in which the nth 
occurrence of the string is located are copied into the output file. 

The string must begin in column 1 of the matched line. The line is 
printed if VERIFY ON is in effect. This command can be used only in 
block mode. 

Format 

[n]PFind string 



2. 4. 39 PAGE LOCATE 

This command causes a search of the current block, starting at the 
line following the current line, and of successive blocks until the 
nth occurrence of the string has been located. Text from the current 
block buffer is written into the output file. The string can occur 
any place in the lines checked. The line is printed if the VERIFY ON 
command is in effect. This command can be used only in block mode. 



READ IN] 
READ IN] 
READ IN] 
READ IN] 
READ IN] 
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Format 

[n]PLocate string 

This command is used in the same manner as the LOCATE command 
except that the specified string can be in a block other than the 
current block. 

PL leaves the current line pointer at end-of-file if it cannot 
locate the string. 



2.4.40 PASTE 

This command is identical to the LINE CHANGE command except that all 
lines remaining in the input file or block buffer are searched and all 
occurrences of stringl are replaced with string2. Modified lines are 
printed if the VERIFY ON command is in effect. If stringl is given, 
but no match is found, EDI returns the asterisk (*) prompt. When the 
command completes, the line pointer is at the top of the buffer or 
input file. 

Format 

PAste /str ingl/string2 [/] 
Example 

If the lines remaining in the block buffer contain the following 
text : 

YIGER, YIGER, BURNING BRIGHY 
IN YHE FORESYS OF YHE NIGHY 

they can be corrected with the following command: 
*PA/Y/T 

If the VERIFY ON command is in effect, all corrected lines are 
printed. To discontinue printing, type CTRL/O. 



2.4.41 PRINT 

PRINT displays the current line and the next n-1 lines at the 
terminal. The last line printed becomes the current line. 

Format 

Print [n] 

For examples and information on how to use PRINT, refer to Section 
2. 2. 14. 



2.4.42 READ 

This command reads the next n blocks of text into the block buffer. 
If a block is already in the buffer, the new block(s) is (are) 
appended to it. 

EDI must be in block mode before this command can be executed. 
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A READ command cannot exceed the buffer capacity. If you issue a READ 
that is too large, EDI fills its buffer and then issues the following 
message : 



[BUFFER CAPACITY EXCEEDED BY] 
<of fending line> 
[LINE DELETED] 



You may get this message after issuing a READ n command, where n is 2 
or larger, unless you have used the SIZE command to reduce the number 
of lines per block below its initial number. 



Format 



RE Ad [n] 

If n is not specified, a value of 1 is assumed. The value of n 
must be positive. 



Example 



*SIZE 15 
*READ 4 



This example reads four 15-line blocks of the input file into the 
block buffer. 



2. 4. 43 RENEW 



RENEW writes the current block buffer into the output file and reads a 
new block from the input file. Renew is used only in block mode. 



Format 



RENew [n] 



For examples and information on how to use RENEW, refer to Section 
2. 2. 15. 



2.4.44 The RETURN Key 

In edit, mode, the RETURN key represents the return that displays the 
next line in the file or block buffer. In input mode, entering the 
RETURN returns EDI to edit mode. For information on EDI command 
modes, refer to Section 2.1.2. For information on the RETURN key, 
refer to Section 2.2.16. 



2.4.45 RETYPE 

RETYPE replaces the current line with string. 
Format 

Retype [string] 

For information on how to use RETYPE, refer to Section 2.2.17. 
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2.4.46 SAVE 

This command causes the current line, and the next n-1 lines, to be 
saved in the specified file. If the file already exists, a new 
version is created. 

If no file is specified, the save file generated has the name 
SAVE.TMP. SAVE puts the temporary file in the UFD on the device for 
the file you are editing. 

The input file or buffer information that is transferred to the SAVE 
file remains intact. The new current line is the last line saved. 
The SAVE command does not delete lines in the block buffer or input 
file. 

Format 

SAve[n] [filespec] 
Example 

You can save and later insert small groups of lines in several 
places in an output file by using the SAVE and UNSAVE commands. 
For example, a file called EDIT. MAC contains six lines that you 
want to insert at several points in another file called HELP. MAC. 
The procedure is: 

1. Start an editing session using EDIT. MAC as the input 
file. 

2. Locate the lines to be inserted into HELP. MAC. 

3. Issue a SAVE 6 command. (This copies the six lines to 
be saved into the file SAVE.TMP.) 

4. Issue a KILL command to terminate the editing session. 

5. Start a new editing session using HELP. MAC as the input 
file. 

6. Locate each place the six lines are to be inserted and 
issue the UNSAVE command. 

7. Make further edits to the input file, as desired, or 
EXIT. 

EDI does not delete the save file. It remains on the specified 
volume until deleted. 



2.4.47 SEARCH & CHANGE 

This command causes a search for stringl in the block buffer (block 
mode) or input file (line-by-line mode), beginning at the current 
line. The string may occur anywhere in the line. When stringl is 
located, it is replaced by string2. The located line becomes the 
current line. 

If stringl is not specified, EDI prints the error message for illegal 
string construction. The new current line is printed if the VERIFY ON 
command is in effect. If stringl is given, but EDI cannot locate the 
string, EDI returns the asterisk (*) prompt and the line pointer is 
positioned at the end-of-file or the bottom of the block buffer. 
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Format 

SC /stringl/string2 [/] 
Example 

If the following incorrect line is contained in the current 
block : 

THES IS THE LINE TO BE ISSUED, 
the following commands can correct the error: 
*V ON 

*SC /THES/THIS/ 

THIS IS THE LINE TO BE ISSUED. 

The corrected line is printed since the VERIFY ON command is in 
effect. 



2.4.48 SELECT PRIMARY 

This command selects the primary file for input. It allows you to 
reestablish the primary input file as the file from which text is 
read . 

Format 

SP 

Example 



♦OPENS SECOND. MAC 
*SS 

♦RENEW 10 

♦CLOSES 

*SP 

This example directs EDI to: 

1. Open the secondary file SECOND. MAC. 

2. Select SECOND. MAC as the secondary input file. 



3. Read ten consecutive block buffers from the secondary 
input file into the block buffer. The first nine blocks 
are automatically transferred to the output file. 

4. Close the secondary input file SECOND. MAC. The 
secondary file need not be closed before the primary 
file is reselected for input. 

5. Reselect the primary input file for input. 
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2.4.49 SELECT SECONDARY 

With this command, you select the secondary file as the input file. 
Format 
SS 

Example 

To add text to the output file from a secondary input file, you 
must first open the secondary input file and select it for input. 
The use of the SS command is illustrated in the example presented 
in Section 2. 4. 28. 



2.4.50 SIZE 

This command allows you to specify the maximum number of lines to be 
read into the block buffer on a single READ or RENEW command. The 
default value for SIZE depends on your exact system configuration. 
Initially, EDI determines how much buffer space it has and divides 
that by 132(10), the maximum line size, to set the number of lines 
read in. In no case can it be less than 38 lines. (See the 
discussion of block mode in Section 2.1.3.) 

Format 

SIZE n 
Example 

*SIZE 50 

This command conditions EDI to read 50 lines into the block 
buffer during a single READ or RENEW command. 



2.4.51 TAB ON/OFF 

This command turns automatic tabbing on or off. The automatic tab 
feature is useful for MACRO-11 language input. TAB OFF is the default 
at the start of an editing session. When TAB ON is in effect, a tab 
(equivalent to eight spaces) is automatically inserted at the 
beginning of each input line unless the line either begins with a 
label followed by a colon or contains a semicolon in the first column. 

Format 



TAb [ON] 

or 
TAb OFF 

If neither ON nor OFF is specified when a TAB command is issued, 
ON is assumed. 
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Example 

*TAB ON 
*I 

; THIS IS A SAMPLE OF TABBING. 
THIS LINE GETS A TAB 
1: THIS ONE DOESN'T 
END 

*TAB OFF 
*N -3 
*P 4 

; THIS IS A SAMPLE OF TABBING. 

THIS LINE GETS A TAB 
1: THIS ONE DOESN'T 

END 



2.4.52 TOP 

TOP sets the current line pointer to the top of the block buffer (in 
block mode) or to the top of the file (in line-by-line mode). In 
line-by-line mode, TOP creates a new version of the file. When the 
current line pointer is positioned by means of TOP, you can insert 
lines preceding the first line in the file. 

Format 

Top 

For examples and information on how to use TOP, refer to Section 
2. 2. 19. 



2.4.53 TOP OF FILE (TOF) 

TOF returns the current line pointer to the first line of the file and 
leaves you in block mode. TOF copies the input file to the output 
file, closes both, and opens the latest version of the file as the 
input file. 

Format 

TOF 

For examples and information on how to use TOF, refer to Section 
2. 2. 18. 



2.4.54 TYPE 

This command is similar to the PRINT command (Section 2.2.14). In 
line-by-line mode, the two are identical. In block mode, TYPE does 
not move the line pointer after displaying the requested text unless 
end-of-block is encountered. In this case, the line pointer remains 
at the last line before the end-of-block. 

If n is not specified, a value of 1 is assumed. 
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TYpe [n] 
Example 

See the example of the PRINT command (Section 2.2.14). 
2.4.55 UNSAVE 

This command retrieves all the lines in a specified file and copies 
them after the current line. If no file is specified, the default 
file is SAVE.TMP. The new current line pointer is positioned at the 
last line retrieved from the file. The file used in this command can 
be any text file. It is often the file created with a SAVE command. 

Format 

UNSave [filespec] 
Example 

File SEC.DAT;1 contains a group of lines to be inserted after the 
current line. The following command performs the desired 
operation . 

*UNS SEC. DAT; 1 

Section 2.6.2 contains an example using the SAVE and UNSAVE 
commands. 



2.4.56 UPPER CASE ON/OFF 

This command allows you to enter lowercase characters from a terminal 
and have them converted to uppercase characters. If UPPER CASE OFF is 
issued, all input characters are accepted as they are entered, 
including the EDI commands. 

Format 

UC [ON] 

or 
UC OFF 

If neither ON nor OFF is specified, then ON is assumed. 
Example 

*UC OFF 

*I this line is entered in lowercase 
*UC ON 

*I this line is converted to uppercase 

Assuming that the input terminal is capable of generating 
lowercase input, the commands in the example would create the 
following lines in the output file. 

this line is entered in lower case 
THIS LINE IS CONVERTED TO UPPER CASE 
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However, in both instances, the characters are converted to 
uppercase before the file is closed. 

To create a file containing lowercase characters, use the MCR SET 
/LOWER =TI: or the DC L SET TERM LOWER command and the EDI UC OFF 
command . 



2.4.57 VERIFY ON/OFF 

This command controls the display of lines specified by the LOCATE and 
CHANGE commands. Use VERIFY ON to display a line located by the 
LOCATE command or to display a line changed by the CHANGE command. 
Use VERIFY OFF to inhibit the display of these lines. VERIFY ON is 
the default when EDI is started. 

Format 

Verify [ON] 
or 

Verify OFF 

If neither ON nor OFF is specified, ON is assumed. 
Example 

*V OFF 
*L VERIFY 
*P 

LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON 

*N -2 

*V ON 

*L VERIFY 

LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON 

In this example, the PRINT command is issued to demonstrate that 
the desired line has been located when VERIFY is OFF, but when 
the LOCATE command is reissued with VERIFY ON, EDI automatically 
prints the line. 



2.4.58 WRITE 

This command causes the entire contents of the block buffer to be 
written into the output file. The block buffer is then erased. 

EDI must be in block mode before this command can be executed. 

Format 

Write 

Example 

*w 

*REA 2 

In this example, the block buffer is written into the output file 
and the block buffer is erased. Then, the next two blocks are 
read into the block buffer. 
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2. 5 EDI USAGE NOTES 

The following points contain general information involving 
restrictions on use of EDI, system device considerations, and general 
usage rules. 

• EDI can operate only on Files-11 format files and rejects all 
other file formats. 

• The output file generated by EDI always resides on the same 
device as the input file. The output file cannot be directed 
to another device. For example, to edit a file on DECtape and 
store the resulting file on disk, do one of the following: 

- Transfer the file to disk and perform the editing there. 

- Edit the file on DECtape and then use PIP or FLX to transfer 
the file to disk. 

• To use a device other than SY: , mount it with the MOUNT 
command . 

• To edit a version of a file other than the latest one, 
explicitly state the desired version number in the file 
specification. This file is opened as the input file. The 
version number of the output file is one greater than the 
latest version of the file. 

• Some EDI commands (such as TOF and TOP, when it is used in 
line-by-line mode) implicitly generate multiple versions of a 
file. In the execution of such commands, EDI copies the 
remainder of the input file into the output file and closes 
both of them. It then opens the latest version of the file 
and uses it as input. This ensures the editing of the latest 
version of the file and provides periodic backup. To delete 
any unwanted versions, use PIP with the /PURGE switch or the 
DCL DELETE command. 

• EDI accepts variable-length input lines up to 132(10) 
characters long. 

• The record type of output files edited by EDI is always 
variable-length . 

• EDI preserves the record attributes of the input file. For 
example, the FORTRAN carriage control attribute is preserved 
in the output file. 

• Line feed characters may be entered in files, but are 
interpreted by EDI as termination characters. You should 
avoid using them since they cause unpredictable results when 
the file is edited a second time. 

• EDI cannot process a file that contains embedded carriage 
control characters, such as PIP directory listings and TKB map 
files. To reformat such a file for EDI processing, copy the 
file to a DOS-11 volume and then back to your original volume 
using FLX. EDI can then process the file. 
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2.6 SAMPLE EDITING OPERATIONS 

Sample editing operations are included in this section to illustrate 
how the various EDI commands can be used: 

• A file is edited using a few basic EDI commands. 

• Two save files are generated, modified, and appended to the 
original file. Any closed file may be appended to or inserted 
within an open file in the manner shown in the second example. 

• An immediate macro command is defined and executed in a single 
step. 

• A file containing errors is edited using the macro commands. 



2.6.1 Pile Editing Sample 



>EDI PRTBLD.CMD 
[PAGE 1] 
*P * 

COMMAND FILE TO BUILD 
PRNT SYMBIONT 
FOR RSX-11M MAXXED SYSTEM 



[1, 54]PRT/MM/-CP,LP:=PRTBLD/MP 

OPTIONS 
STACK=40 

PAR=PARK: 0:10000 

UNITS=4 

TASK=PRT. . . 

ASG=CO:2,LP:3 

PRI=60 

UC=[10,1] 

SPECIFY 

SPECIFY FLAG WHICH CONTROLS 
FILE DELETION AFTER PRINTING 

TO ENABLE DELETION USE 

GB LPAT=PRT ; $DE LET : 1 

TO INHIBIT DELETION USE 

DEFAULT FROM ASSEMBLY IS 
FILE DELETION ENARBLED 



GBLPAT=PRT : $DELET 
/ 

[*E0B*] 



File PRTBLD.CMD is opened for editing. A PRINT * command 
is issued to print the contents of the file. The following 
errors are detected: 



1 - PRNT should be PRINT. 

2 - MAXXED should be MAPPED. 



3 - /-CP should be /CP. 

4 - INPUT should be appended to the line containing the 

word OPTIONS. 

5 - PARK should be PAR4K. 



UC should be UIC 

The line containing ; SPECIFY should be deleted. 



The comment line containing the format used to inhibit 
deletion is missing. 
ENARBLED should be ENABLED. 



- A :1 should be appended to the line following the 
word $DELET. 

The end of buffer is reached and EDI causes the EOB message 
to be printed. 
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*TOP 

[PAGE 1] 

*PL PRNT 

; PRNT SYMBIONT 

*C/RN/RIN/ 

; PRINT SYMBIONT 

* 

; FOR RSX-11M MAXXED SYSTEM 
*C/XX/PP/ 

; FOR RSX-11M MAPPED SYSTEM 
*NP 3 

[1,54] PRT/MM/-C P , LP : =PRTB LD/MP 
*C,/-CP,/CP, 

[1,54] PRT/MM/CP , LP : =PRTB LD/MP 
*PL PAR= 

PAR-PARK: 0: 10000 

*C/RK/R4K/ 

PAR«PAR4K: 0: 10000 

*NP -3 

; OPTIONS 

*AP INPUT 

; OPTIONS INPUT 

*PL UC 

UC»[10,1] 

♦C/UC/UIC/ 

UIC=[10,1] 

* 



* 

; SPECIFY 
*DP 

; SPECIFY FLAG WHICH CONTROLS 
*PL INH 

; TO INHIBIT DELETION USE 
*I 

GBLPAT=PRT: $DELET: 

*PL RB 

; FILE DELETION ENARBLED 
*C/R// 

; FILE DELETION ENABLED 



GBLPAT=PRT:$DELET 
*AP :1 

GBLPAT=PRT: $DELET: 1 
*TOF 

[PAGE 1] 
*p * 

; COMMAND FILE TO BUILD 

; PRINT SYMBIONT 

; FOR RSX-11M MAPPED SYSTEM 



A TOP command is issued to move the line pointer to top of 
file and editing is started. 

1 - A PAGE LOCATE command is issued to locate the first 

line in error and the line is printed automatically. 
A CHANGE command is issued to correct the line 
and the corrected line is displayed automatically. 

2 - A RETURN is entered following the prompt to 

move the line pointer and print the next line in error. 
A CHANGE command is issued to correct the line and the 
corrected line is displayed automatically. 

3 - A NEXT PRINT 3 command is issued to locate the 

next line in error and the line is printed. A CHANGE 
command is issued to correct the line and the corrected 
line is displayed automatically. 

4 - A PAGE LOCATE command is issued to locate the next 

line in error and the line is printed automatically. A 
CHANGE command is issued to correct the line and the 
corrected line is displayed automatically. 

5 - A line in error was bypassed by mistake; therefore, a 

NEXT PRINT -3 command is issued to back the line 
pointer up. An ADD AND PRINT command is used to correct 
the line 

6 - A PAGE LOCATE command is used to locate the next line 

in error and the line is printed automatically. 
A CHANGE command is issued to correct the line and 
the corrected line is displayed automatically. 

7 - The line pointer is moved down two lines by means 

of a RETURN option to locate the next 

line in error. A DELETE AND PRINT command is issued to 
delete the line containing ; SPECIFY and print 
the next line. 

8 - A PAGE LOCATE command is issued to locate the 

point in the file where the new comment lines 
are to be inserted. EDI is switched to the Input 
mode, two lines are entered, and EDI is switched 
back to Edit mode by entering a RETURN as 
the first character in the line. 

9 - A PAGE LOCATE command is issued to locate the next 

line in error. A CHANGE command is issued to 
correct the spelling error. The line is displayed 
automatically. 

10 - The line pointer is moved down two lines using two 
RETURNS to locate the last line in error. 
An ADD AND PRINT command is issued to append 
:1 following the word $DELET. 

The necessary corrections are complete, so the line pointer 
is moved to the top of the file by means of a TOF command. 
A PRINT * command is issued to print the complete file 
with all corrections 
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[1 , 54] PRT/MM/CP, LP: =PRTBLD/MP 

; OPTIONS INPUT 

STACK=40 

PAR=PAR4K: 0:10000 
UNITS=4 
TASK=PRT. . . 
ASG»CO:2,LP: 3 
PRI=60 
UIC=[10,1] 

; SPECIFY FLAG WHICH CONTROLS 
; FILE DELETION AFTER PRINTING 

; TO ENABLE DELETION USE 

; GB LPAT=PRT : $DE LET : 1 

; TO INHIBIT DELETION USE 

; GB LPAT=PRT : $DE LET : 

; DEFAULT FROM ASSEMBLY IS 
; FILE DELETION ENABLED 

GB LPAT=PRT : $DELET : 1 
/ 

[*EOB*] 

*EX An EXIT command is issued to close the file and 

[EXIT] terminate the editing session. 



2.6.2 SAVE and UNSAVE Sample 



*LI 

THIS IS LINE 

THIS IS LINE 

THIS IS LINE 

THIS IS LINE 

THIS IS LINE 
[*EOB*] 
*T 

*SA 5 SAV1.DAT 



*T 

*SA 5 SAV2.DAT 
*CL 

EDI >S AVI. DAT 
[PAGE 1] 
*LI 

THIS IS LINE 
THIS IS LINE 
THIS IS LINE 
THIS IS LINE 
THIS IS LINE 
[*EOB*] 



PAGE 
PAGE 
PAGE 
PAGE 
PAGE 



PAGE 
PAGE 
PAGE 
PAGE 
PAGE 



The file to be used in this example is 
printed using the LIST command. 



The line pointer is returned to the top. 
A SAVE command is used to save the 
five lines in a separate file. 

The line pointer is returned to the top. 

A second SAVE command is used to generate 

a second saved file. The primary input file is closed. 

The first save file is opened and a 

LIST command is used to display the file. 
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*PA/PAGE 1/PAGE 2/ 

THIS IS LINE 1 PAGE 2 

THIS IS LINE 2 PAGE 2 

THIS IS LINE 3 PAGE 2 

THIS IS LINE 4 PAGE 2 

THIS IS LINE 5 PAGE 2 
*CL 

EDI>SAVE2. DAT 
[PAGE 1] 
*LI 

THIS IS LINE 1 PAGE 1 

THIS IS LINE 2 PAGE 1 

THIS IS LINE 3 PAGE 1 

THIS IS LINE 4 PAGE 1 

THIS IS LINE 5 PAGE 1 
[*EOB*l 

*PA/PAGE 1/PAGE 3/ 

THIS IS LINE 1 PAGE 3 

THIS IS LINE 2 PAGE 3 

THIS IS LINE 3 PAGE 3 

THIS IS LINE 4 PAGE 3 

THIS IS LINE 5 PAGE 3 
*CL 

EDI>START. DAT 
[PAGE 1] 
*BO 

THIS IS LINE 5 PAGE 1 

*UNS SAV1.DAT 

*UNS SAV2.DAT 

*T 

*LI 

THIS IS LINE 1 PAGE 1 

THIS IS LINE 2 PAGE 1 

THIS IS LINE 3 PAGE 1 

THIS IS LINE 4 PAGE 1 

THIS IS LINE 5 PAGE 1 

THIS IS LINE 1 PAGE 2 

THIS IS LINE 2 PAGE 2 

THIS IS LINE 3 PAGE 2 

THIS IS LINE 4 PAGE 2 

THIS IS LINE 5 PAGE 2 

THIS IS LINE 1 PAGE 3 

THIS IS LINE 2 PAGE 3 

THIS IS LINE 3 PAGE 3 

THIS IS LINE 4 PAGE 3 

THIS IS LINE 5 PAGE 3 
[*EOB*] 
*EX 
[EXIT] 



A PASTE command is used to change 
PAGE 1 to PAGE 2 in all lines. 



The first save file is closed. 
The second save file is opened. 

The LIST command is used to display 
the contents of the file. 



A PASTE command is used to change 
PAGE 1 to PAGE 3 in all lines. 



The second save file is closed. 

The original input file is opened again. 



The last line in the file is located. 

Two UNSAVE commands are used to 

append the two save files to the 

original input file. 

A LIST command is used to 

display the contents of the 

combined file. 
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2. 6. 


3 


Use i 


of 


MACRO 


*LI 










ABC 


IN 


LINE 


1 


- ABC 


ABC 


IN 


LINE 


2 


- ABC 


ABC 


IN 


LINE 


3 


- ABC 


ABC 


IN 


LINE 


4 


- ABC 


ABC 


IN 


LINE 


5 


- ABC 



A LIST command is issued to print 
the file used in this example. 



ABC 


IN 


LINE 


N 




ABC 




[*EOB*] 












*4<F 


ABC&C/ABC/DEF/> 


The immediate macro is defined 


ABC 


IN 


LINE 


1 




ABC 


and executed to find the first 


DEF 


IN 


LINE 


1 




ABC 


four lines that start with ABC 


ABC 


IN 


LINE 


2 




ABC 


and change the first occurrence 


DEF 


IN 


LINE 


2 




ABC 


of the string ABC to DEF. 


ABC 


IN 


LINE 


3 




ABC 


The FIND command causes the line 


DEF 


IN 


LINE 


3 




ABC 


to be printed before the change. 


ABC 


IN 


LINE 


4 




ABC 


The CHANGE command causes 


DEF 


IN 


LINE 


4 




ABC 


the line to be printed after 



the change. 



2.6.4 Use of Macro Commands 



*LI 

THIS LITTLE FILE HAS 
MANY CONNON ETTORS SO 
WE CAN SHOW YOU HOW 
YHE MACRO CONNANDS CAN 
BE USED. 

FIRST, YHE DESIRED MACRO 
MUST BE DEFINED; YHE LINE 
POINTER IS MOVED TO A LINE 
WITH AN ETTOR; AND YHEN, YHE 
MACRO EXECUTE CONNAND 
IS ISSUED TO COTTECT YHE 
ETTOR 
[*EOB*] 

♦MACRO 1 C/NN/MM/ 
♦MACRO 2 SC/TT/RR/ 
♦MACRO 3 PA/YHE/THE/ 
*M3 

THE MACRO CONNANDS CAN 
FIRST, THE DESIRED MACRO 
MUST BE DEFINED; THE LINE 
WITH AN ETTOR, AND THEN, THE 
IS ISSUED TO COTTECT THE 
*NP2 

MANY CONNON ETTORS SO 
*M1 

MANY COMMON ETTORS SO 
*M2 



The LIST command is used to print the 
file and the file is checked for errors. 
The following errors are located. 

1. The string NN is used in place 
of MM (see macro 1). 

2. The string TT is used in place 
of RR (see macro 2). 

3. The string YHE is used in place 
of THE (see macro 3). 



The three macro definitions that will 
correct the errors are typed. 

Macro 3 is used to change all YHE 
strings to THE. 



NP2 is used to locate a line with errors, 
Ml is used to change NN to MM. 
M2 is used to change TT to RR. 
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MANY COMMON ERRORS SO 
*NP2 

THE MACRO CONNANDS CAN 
*M1 

THE MACRO COMMANDS CAN 
*M2 

WITH AN ERROR; AND THEN, THE 

MACRO EXECUTE CONNAND 
*M1 

MACRO EXECUTE COMMAND 
*M2 

IS ISSUED TO CORRECT THE 
*M2 

ERROR 

*T 

*LI 

THIS LITTLE FILE HAS 
MANY COMMON ERRORS SO 
WE CAN SHOW YOU HOW 
THE MACRO COMMANDS CAN 
BE USED. 

FIRST, THE DESIRED MACRO 
MUST BE DEFINED; THE LINE 
POINTER IS MOVED TO A LINE 
WITH AN ERROR; AND THEN, THE 
MACRO EXECUTE COMMAND 
IS ISSUED TO CORRECT THE 
ERROR. 
[*EOB*] 



2.7 EDI ERROR MESSAGES 

The four classes of EDI error messages are: 

• Command level information messages 

• File access error messages 

• Error messages requiring EDI to restart 

• Fatal error messages 

The following sections describe all the messages that can be displayed 
in each class. If the recovery procedure is not evident, a suggested 
user action is given. 



NP2 is used to locate the next line in error. 

Ml is used to change NN to MM. 

M2 is used to locate the next TT string 
and change it to RR. 

A RETURN is used here to locate the next line 
in error. 

Ml is used to change NN to MM. 

M2 is used to locate the next TT string and 
change it to RR. 

M2 is used to locate the last error in the 
file and correct it. 

After all lines have been corrected, the 
file is printed using the LIST command. 
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2.7.1 Command Level Information Messages 

Messages in this class indicate information that is designed to be 
helpful to you or to identify errors that were encountered in the 
previous command. All messages in this class are enclosed within 
square brackets and are followed by a prompt for a new command. For 
example, the following output occurs if a DELETE command encounters an 
end-of-buf f er in block mode: 

[*EOB*] 
* 

The messages in this class follow. 

[BUFFER CAPACITY EXCEEDED BY] 
offending line 
[LINE DELETED] 

Explanation: A READ, UNSAVE, INSERT, or OVERLAY command has 
exceeded the capacity of the block buffer. The line that caused 
the overflow is displayed and deleted. 

User Action: If a new file is being created, empty the buffer 
with a WRITE command and continue the editing session. 

If an existing file is being edited, it may be possible to 
continue by using a RENEW or WRITE command. Otherwise, use the 
CLOSE command to close the output file and save all edits. 
Reopen the output file as the input file and, using the SIZE 
command, reduce the number of lines read into each buffer. Then, 
using the PAGE LOCATE command, search to the position in the file 
where editing is to continue. 

Occasionally, this message results when you try to open a file 
that was not created by EDI. You can overcome this difficulty by 
using the SIZE command procedure that follows: 

1. Type KILL. 

2. When EDI prompts for a new file specification, enter a 
nonexistent file name. EDI creates a new file and enters 
input mode. 

3. Use the RETURN key to enter edit mode. 

4. Using the SIZE command, reduce the number of lines read into 
each buffer. 

5. Use the KILL command to abandon the file. 

6. When EDI prompts for a new file specification, enter the name 
of the desired file. 



[CREATING NEW FILE] 
INPUT 

Explanation: The input file specified with the command does not 
exist and EDI has created a new file. EDI automatically enters 
input mode and waits for the input of text lines. 
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User Action: If you intend to create a new file, continue 
entering new lines as required. Otherwise, enter edit mode by 
pressing RETURN and use the KILL command to delete the undesired 
new file. When EDI prompts for a new file specification, enter 
the correct file specification. 



[ILL CMD] 

Explanation: Either EDI does not recognize the command or you 
have entered a command that is not compatible with the current 
mode (for example, a READ command in line-by-line mode). 



[ILL NUM] 

Explanation: Either you have supplied a nonnumeric character 
when a numeric is required or you have given a negative number 
when a positive number is required. 



[ILL STRING CONST] 

Explanation: A search string specified in a CHANGE, LC, PASTE, 

or SC command does not contain a matching string termination 

character (for example, PASTE /ALPHABETA, instead of PASTE 
/ALPHA/BETA) . 



[ILLEGAL IN BLOCK ON MODE] 

Explanation: You have tried to execute a command that is illegal 
in block mode, such as FILE or OUTPUT ON/OFF. 



[ILLEGAL FILE NAME GIVEN IN CLOSE OR EXIT] 
or 

[FILE WAS NOT RENAMED] 

Explanation: A syntactically incorrect file specification was 
given in a CLOSE or EXIT command, the attempt to rename the 
output file failed, or the attempt to EXit or Close to rename the 
file to another device failed. 

User Action: Use the PIP /RE switch or the DC L RENAME command to 
rename the file, if desired. 



[MACRO NOT DEFINED] 

Explanation: You have tried to execute a macro with the M 
command, but the specified macro has not been defined. 

User Action: Use the MACRO command to define the desired macro 
and then execute it with the M command. 
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[MACRO NUMERIC ARG UNDEFINED] 

Explanation: You have tried to execute a macro without supplying 
a numeric argument. The macro definition contains a percent (%) 
character and thus demands a numeric argument. 

User Action: Reenter the command line, specifying the 
appropriate numeric argument. 



[MCALL FILE DOES NOT EXIST] 

Explanation: You have issued an MCALL command to retrieve a set 
of macros, but the file MCALL cannot be found. 

User Action: The desired set of macro definitions may exist 
under another User File Directory. If this is the case, use PIP 
or the appropriate DCL commands to copy or rename the MCALL file 
into the current directory. 



[NO INPUT FILE OPEN] 

Explanation: You have issued a PAGE, READ, or RENEW command 
while a new file is being created (that is, while there is no 
input file) . These commands can be executed only when an 
existing file is being edited. 



[NO MATCH] 

Explanation: You have issued a CHANGE command with a string to 
be changed that is not in the current line. 



[OVERLAYING PREVIOUSLY DEFINED MACRO] 

Explanation: You have issued a MACRO command that redefines a 
previously defined macro. This message lets you know that the 
previous definition is no longer in effect. 



[SAVE FILE DOES NOT EXIST] 

Explanation: The file specified in an UNSAVE command cannot be 
located . 

User Action: If you provided a file specification, make sure it 
is correct. If you did not provide a file specification, this 
message means that no previous SAVE command (without file 
specification) was issued. 



[SECONDARY FILE ALREADY OPEN] 

Explanation: You may have tried to open a secondary input file 
while another secondary file is still open. Or you may have a 
secondary file open when you issue a CLOSE or KILL command, or 
when EDI encounters an error and is forced to restart. The 
former case represents an error. The latter informs you that you 
still have a secondary file open. 

User Action: Close the secondary input file using the CLOSES 
command and then open the desired secondary file with the OPENS 
command . 
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[SECONDARY FILE CURRENTLY SELECTED FOR INPUT] 

Explanation: You have issued a CLOSE or KILL command or an error 
has caused EDI to restart when a secondary input file is open and 
selected for input. 

User Action: Issue an SP command, then a CLOSES command. 



[SYNTAX ERROR] 

Explanation: You entered a command that is syntactically 
incorrect . 



[TOO MANY CHARS] 

Explanation: A CHANGE, LC, PASTE, SC, or ADD command has 
resulted in a line that contains too many characters. EDI limits 
the length of a line to 132(10) characters. 

User Action: Reenter the command line to ensure that the line is 
val id . 



[*BOB*] 

Explanation: You have reached the beg inning-of-buf f er . The 
current line pointer is positioned just before the first line in 
the buffer. Thus, new text lines can be entered before the first 
1 ine . 



[*EOB*] 

Explanation: You have reached the end-of-buf f er . The current 
line pointer now points to the end of the buffer. Thus, if new 
lines are inserted, they appear after the last text in the 
buffer . 



[*EOF*] 

Explanation: You have reached the end-of-file on the input file. 

User Action: If the editing session is complete, use the CLOSE 
or EXIT command to close the output file. Otherwise, use the TOF 
command to return to the first block in the file. 



2.7.2 File Access Error Messages 

Messages in this class mean that you have tried to access directories, 
files, or devices that are not present in the host system. Each 
message is prefixed with: 

EDI — 

After the message is displayed, EDI returns to command level and 
prints an asterisk to request input. 

The messages in this class follow. 
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EDI — BAD FILE NAME 

Explanation: EDI did not accept the file name. The most common 
error is a file name containing embedded blanks. 

User Action: Make sure that the file name is correct, then 
reenter it. 



EDI — DEVICE NOT IN SYSTEM 

Explanation: You have given a FILE, OPENS, SAVE, or UNSAVE 

command and specified a device that does not exist in the host 
system . 

User Action: Reenter the command line, specifying only devices 

available in the system. 



EDI ~ FILE DOES NOT EXIST 

Explanation: You have given a FILE or SAVE command and specified 
a User File Directory that does not exist on the specified 
vol ume. 



NOTE 

The remaining error messages in this 
class should not occur and represent 
failures in EDI. If such errors 
persist, submit a Software Performance 
Report (SPR). 



EDI — BAD DEVICE NAME 



EDI — DEVICE NOT READY 



EDI — FILE ALREADY OPEN 



EDI — RENAME NAME ALREADY IN USE 



EDI — RENAME ON TWO DIFFERENT DEVICES 



EDI — WRITE ATTEMPT TO LOCKED UNIT 



2.7.3 Error Messages Requiring EDI Restart 

The error messages described in this section are caused by conditions 
that make it impossible for EDI to continue the current editing 
session. EDI closes all open files (with the exception of any open 
secondary input file), reinitializes, and then prompts for the next 
file to be edited. 
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EDI — PRIMARY FILE NOT PROPERLY CLOSED 

Explanation: When the primary input file was last written, a 
close check was specified and the writing task did not properly 
close the file (for example, the task was aborted). Thus, the 
file attributes were not written and the file may contain 
inconsistent data. 

User Action: Exit from EDI by pressing RETURN or CTRL/Z. Use 
the PIP /UN switch to unlock the file. Reinitiate EDI and try to 
recover the data in the file. 



EDI — PRIVILEGE VIOLATION 

Explanation: A privilege violation occurred during a file access 
for one of the following reasons: 

1. The specified volume is not mounted. 

2. The UIC under which EDI is running does not possess the 
necessary privileges to access the specified directory. 

3. The UIC is not privileged to access the specified file. 

User Action: If the volume is not mounted, then mount it using 
the MOUNT command. Otherwise, reinitiate EDI under a UIC that 
has appropriate access privileges to both the specified directory 
and file. 



EDI — RECORD IS TOO LARGE FOR USER BUFFER 

Explanation: The input file (primary input, secondary input, 
UNSAVE, or MCALL) being accessed was not created by EDI (or SLP) 
and contains records that are too large. The maximum record 
length supported by EDI is 132(10) bytes. 



EDI — SECONDARY FILE NOT PROPERLY CLOSED - NOT USABLE 

Explanation: When the secondary input file was last written, a 
close check was specified and the writing task did not properly 
close the file (for example, the task was aborted). Thus, the 
file attributes were not written and the file may contain 
inconsistent data. 

User Action: Use the PIP /UN switch to unlock the file. 
Reinitiate EDI and try to recover the data in the file. 



EDI — BAD DIRECTORY SYNTAX 

Explanation: Directory field ([g,m]) is in improper format. 



NOTE 

The remaining error messages in this 
class should not occur and represent 
failures in EDI. If such errors 
persist, submit a Software Performance 
Report (SPR). 
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EDI — DUPLICATE ENTRY IN DIRECTORY 



EDI — END OF FILE 



EDI — ILLEGAL RECORD ACCESS BITS - FILE NOT USABLE 



EDI — ILLEGAL RECORD NUMBER - FILE NOT USABLE 



2.7.4 Fatal Error Messages 

The fatal error messages represent system and/or hardware conditions 
that make it impossible for EDI to continue execution. All files are 
closed and EDI terminates its execution. The output file may be 
truncated. Each error message is prefixed with: 

EDI — 

and followed by the exit message: 

[EXIT] 
on the next line. 

You may work with the following procedures on the truncated version of 
an output file to save the editing performed before the fatal error 
occurred . 

1. Use the PIP /RE switch or the DC L RENAME command to rename 
the truncated version of the output file to avoid confusion. 

2. Restart the editing session to the original input file. 

3. Issue an OPENS command, specifying the renamed file as the 
secondary file. 

4. Issue an SS command to select the secondary file for input. 

5. Issue an ERASE command to erase the first block of the input 
file (unless the truncated output file did not contain the 
entire first block). 

6. Issue as many READ 1 and WRITE commands as necessary to reach 
the EOF on the secondary file. 

7. Issue an SP command to select the primary file for input. 

8. Issue a CLOSES command to close the secondary file. 

9. Issue a WRITE command to ensure that the last block was 
written into the output file. 

10. Issue as many READ 1 and ERASE commands as necessary to 
bypass all input file blocks that are complete in the renamed 
file. 

11. Continue the normal editing session. 
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The messages in this class follow. 



EDI — CALLER'S NODES EXHAUSTED 

Explanation: System dynamic storage has been depleted and 
insufficient space is available to allocate the control blocks 
necessary to open, close, read, or write a file. 

User Action: This probably is a system failure, but it could 
also represent a transient overload condition. Wait until system 
load has diminished and reinitiate EDI. 



EDI — DEVICE FULL 

Explanation: Insufficient space exists on the output volume to 
extend an output file (text output, FILE, or SAVE). 

User Action: Determine which volume is being written to. If it 
is required that the specified file be written on this volume, 
then space must be made available. Use PIP to purge (/PU) or 
delete (/DE) unwanted files, or use the DC L PURGE and DELETE 
commands . 



EDI -- FILE HEADER CHECKSUM ERROR 

Explanation: An input file (primary input, secondary input, 
UNSAVE, or MCALL) has a header block that does not contain a 
proper checksum. 

User Action: The file structure on the specified volume is 
damaged. Run the File Structure Verification Utility (VFY) to 
determine the extent of the damage. VFY is described in Chapter 
9. 



EDI — FILE HEADER FULL 

Explanation: Insufficient retrieval pointer space exists in the 
header block to extend an output file (text output, FILE, or 
SAVE ) . 

User Action: Split the file into two or more files and process 
them separately. 



EDI — FILE PROCESSOR DEVICE WRITE ERROR 

Explanation: This error message may indicate that the device 

specified for an output file is wr ite-locked . 

User Action: Unlock the device if it is wri te-locked . 

Otherwise, a hardware problem may exist. Consult your DIGITAL 

Field Service representative. 
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EDI — INDEX FILE FULL 

Explanation: The file header block is not available to create an 
output file (text output, FILE, or SAVE). When a volume is 
initialized, the maximum number of files that may be created on 
the volume is established. Your write request would have 
exceeded this maximum. 

User Action: Determine which volume is being referenced. If it 
is required that the specified file be created on this volume, 
then space must be made available. Use PIP to purge (/PU) or 
delete (/DE) unwanted files^ or use the DCL PURGE or DELETE 
commands . 



NOTE 

The following error messages signify 
hardware problems. If possible, remove 
all important files from the volume, 
then contact your local DIGITAL Field 
Service representative. 



EDI — BAD BLOCK ON DEVICE 



EDI — FILE PROCESSOR DEVICE READ ERROR 



EDI — HARDWARE ERROR ON DEVICE 



EDI — PARITY ERROR ON DEVICE 



NOTE 

The remaining error messages in this 
class should not occur and represent 
failures in EDI. If such a failure 
occurs, contact your local DIGITAL Field 
Service representative. 



EDI — BAD DIRECTORY FILE 



EDI — BAD PARAMETERS ON A QIO 



EDI — INVALID FUNCTION CODE ON A QIO 



EDI — NO BLOCKS LEFT 



EDI — REQUEST TERMINATED 
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EDI — UNEXPECTED ERROR - EDITOR WILL ABORT 
EDI — WRITE ATTRIBUTE DATA FORMAT ERROR 
TASK "...EDI" TERMINATED 
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CHAPTER 3 
PERIPHERAL INTERCHANGE PROGRAM (PIP) 



The Peripheral Interchange Program (PIP) is a file utility program 
that transfers data files from one standard Files-11 device to 
another. PIP also performs file control functions. Some of the 
functions PIP performs are: 

• Copying files from one device to another 

• Deleting files 

• Renaming files 

• Listing file directories 

• Setting the default device and UIC for PIP operations 

• Unlocking files 

• Spooling files 

You invoke the PIP utility using any of the methods for invoking a 
utility described in Chapter 1. You invoke PIP file control functions 
by means of switches and subswitches. 



3.1 PIP COMMAND LINE 

You request PIP functions by entering PIP command lines through the 
initiating terminal or by means of an indirect command file. The 
maximum nesting level for indirect command files is four. (Using 
indirect command files is described in Chapter 1.) The format of PIP 
command lines differs for each function. Therefore, the command line 
formats are described in separate sections. 



3.1.1 PIP Defaults for File Specification Elements 

With the exception of the version number, PIP generally uses the last 
value encountered in the command line as the default. That is, PIP 
uses values you enter to set defaults and changes the default when you 
change the value. Exceptions to this are noted in the descriptions of 
each switch. 

In the following example, T1.MAC;5 sets the defaults for the 
subsequent file specifications in the command line. Then, T2 is 
specified and overrides Tl as the default filename; however, .MAC 
remains the default file type. Finally, . TSK is specified, which 
overrides .MAC as the default, while T2 remains the default file name. 
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Note, in this example, that the version number does not default. 

PIP>T1.MAC; 5,T2, .TSK/BR 

Tl.MAC; 5 
T2.MAC;1 
T2.TSK;3 

Table 3-1 summarizes the rules PIP uses to set defaults. 



Table 3-1 
PIP Default File Specifications 


Element 


Default Value 


d ev i 


For the first" file sDec i f ication . the unit on which 
the user's system disk is mounted (SYO: ) or the 
default that you specify with the /DF switch (see 
Section 3.2.2.6). For subsequent file 
specifications, either you explicitly specify a new 
device or PIP assumes the device from the previous 

o ^-'C \* 1 i. X L O U 1 Ull • 


[ufd] 


For the first file specification, your current User 
Identification .Code or UIC (that is, the UIC under 
which you log on) , the UIC you specify with the SET 
command, or the default you specify with the /DF 
switch (see Section 3.2.2.6). For subsequent file 
specifications, either you explicitly specify a new 
User File Directory or PIP assumes the UFD from the 
previous specification. Only the asterisk 
specification is valid as a wildcard (see Section 
3.1. 3) . 


filename 


No default for the first file specification. For 
subsequent file specifications, the last file name 
that you explicitly specified. Asterisk and/or 
percent sign specifications are valid as wildcards 
(see Section 3.1.3). 


. f iletype 


No default for the first file specification. For 
subsequent file specifications, the last file type 
that you explicitly specified. Asterisk and/or 
percent sign specifications are valid as wildcards 
(see Section 3.1.3). 


; version 


The default for input files is the most recent 
version number. The default for output files is the 
next higher version number, or version 1 if the file 
does not exist in the output directory. An 
exception is the PIP file delete function, which 
requires that a version number be specified. 

An explicit version number is defined to be of the 
form ;n where n is greater than 0. A version number 
of ;-l may be used to specify the oldest version of 
a file. A version number of ;0 or ; may be 
specified to signify the most recent version. In 
certain cases, just the asterisk (wildcard) may be 
specified, as described in Section 3.1.3. 
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3.1.2 PIP Switches and Subswitches 

PIP provides several file control switches and subswitches. A switch 
specification consists of a slash (/) followed by a 2- or 3-character 
switch name. The switch specification is optionally followed by a 
subswitch name separated from the switch name by a slash. The switch 
or subswitch can have arguments that are separated from the switch or 
subswitch name by a colon (:). 

To allow several commands to be performed consecutively, more than one 
command can be specified in a line. To separate each command, the 
ampersand character (&) is used. 

Most of the PIP switches operate on lists of file specifications. The 
exceptions are /DD, /DF, /ID, and /TD, which are used by themselves. 

Table 3-2 lists PIP switches and subswitches and summarizes the 
functions performed by them. The subswitches are listed with their 
respective switches. The switches and subswitches are described in 
detail in Section 3.2.2. 



Table 3-2 
PIP Switches and Subswitches 



Switch 



Subswitch 



Function 



/AP 

/BS:n[. ] 

/CD 

/DE 

/DD 

/DF 
/EN 



/FO 



/LD 



/NV 



/EOF [ .-block :byte] 



/EX 



Appends file(s) to the end of an existing 
file. 

Specifies the file owner for a file. 

Defines the blocksize for magnetic tape. 

Allows the output file to take the creation 
date of the input file rather than the date 
of transfer. 

Deletes one or more files. 
Lists the deleted files. 

Restricts file searches to files created 
during a specified period of time. 

Changes PIP's default device and/or UFD. 

Enters a synonym for a file in a directory 
file. 

Forces the version number of a file to one 
greater than the latest version. 

Specifies the end-of-file pointer for a 
file. 

Excludes one file specification's worth of 
files during file, searches. 



(continued on next page) 
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Table 3-2 (Cont.) 
PIP Switches and Subswitches 



Switch 



Subswi tch 



Function 



/FI : f ilenum rseqnum 



/FR 



/ID 
/LI 



/ME 



/NM 
/PR 



/BR 

/FU[:n[.]] 
/TB 



/BL:n[. ] 

/CO 

/FO 
/NV 

/SU 



/FO 

/GR [ : RWED] 
/OW [ : RWED] 
/SY[:RWED] 
/WO [: RWED] 



Accesses a file by its file identification 
number (file-ID). 

Displays the amount of available space on 
the specified volume, the largest contiguous 
free space on that volume, and the number of 
available file headers. 

Identifies the version of PIP being used. 
Lists directory files. 

Lists a directory file in brief format (an 
alternate mode for the /LI switch) . 

lists a directory file in full format (an 
alternate mode for the /LI switch) . 

Lists the total number of blocks used for a 
directory, along with the total number 
blocks allocated and the number of files in 
that directory (an alternate mode for the 
/LI switch) . 

Concatenates two or more files into one 
file. 

Allocates a number (n) of contiguous blocks. 

Specifies that the output file(s) be 
contiguous . 

Specifies the file ownership for a file. 

Forces the version number of a file to one 
greater than the latest version. 

Supersedes (replaces) an existing file. 

Suppresses certain PIP error messages. 

Changes the protection status of a file. 

Specifies the ownership for a file. 

Sets the read/write/extend/delete protection 
at the group level. 

Sets the read/write/extend/delete protection 
at the owner level. 

Sets the read/write/extend/delete protection 
at the system level. 

Sets the read/write/extend/delete protection 
at the world level. 



(continued on next page) 
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Table 3-2 (Cont.) 
PIP Switches and Subswitches 



Switch 


Subswi tch 


Function 


/PU[ 


:n [ . 


]] 


/t n 


n*>l^i"^c: nhcsnl upr^i'nn f q\ nf a flip. 

Llato LIlc UclcLcU LlXcbi 


/RE 








Renames a file. 


/RM 








Removes a file entry from a directory. 


/RW 








1\C W111UO CI lit CTMUCCA^ L. CI £*CZ • 


/SB 








Specifies that records may span disk block 
boundaries when copied from magnetic tape. 


/SD 








Selectively deletes files by prompting for 
your response before deleting. 


/SP[ 


:n[. 


]] 




Spools files to the line printer for 
printing . 


/SR 








Allows shared reading of a file that has 

d J. i cdU y Uccll \J pcllcU LUI wi l L x iiy uy dUU lhcl 

user or task. 


/TD 








Rp?1t l'fl"^ Flip QPArrhp^ t*n f i 1 oc prpat 1 on 

the current day. 


/TR 








Truncates files to logical end-of-file. 


/UF 








Creates a User File Directory entry on the 
volume to which a file is being transferred. 


/UN 








Unlocks a file. 


/UP 






/FO 


Updates (rewrites) an existing file. 
Specifies the owner for a file. 



Switches and subswitches are described in the following sections. 



3.1.2.1 Switches - PIP accepts some switches with no file 
specification. However, when you use a switch in a command line, it 
must follow the file or UFD specification. It cannot come before the 
device name, the UFD, the file name, file type, or version of the file 
on which it is to operate. 

You may specify a switch once for a list of file specifications. For 
example : 

f ilespecl , f ilespec2, f ilespec3/DE 

The /DE switch applies to all of the file specifications. PIP deletes 
every specified file from its UFD. 



3-5 



PERIPHERAL INTERCHANGE PROGRAM (PIP) 



You specify switch arguments as octal (default), decimal, or 
alphabetic characters, depending on the switch. The sections that 
explain the individual PIP switches discuss these values. 



3.1.2.2 Subswitches - You can apply subswitches to one or more file 
specifications, depending on the placement of the subswitch. 
Subswitches can appear in either the output file specification or the 
input file specification. 

If you place the subswitch in the output file specification, the 
subswitch applies to the entire list of input file specifications. 
For example, the Contiguous Output switch (/CO) is applied to both 
TEST. TSK and SAMP. DAT. (The /CO switch is used with the Copy 
function. See Section 3.2.1.) 



PIP>/C0=TEST.TSK;1,SAMP.DAT;1 



PIP copies TEST. TSK; 1 and SAMP. DAT; 1 such that the copies, TEST. TSK; 2 
and SAMP. DAT; 2, are contiguous. 

If you place the subswitch in the input file specification, it usually 
applies only to the file specification that immediately precedes it. 
In the following example, the New Version subswitch (/NV) is applied 
to the file ASDG . MAC . (The /NV subswitch is being used with the 
Rename switch, /RE.) 



PI P> * . SM P=PRT 2 . QRT , AS DG . MAC/N V, KG . MAC/ RE 



PIP renames the files PRT2.QRT and KG. MAC, but they maintain their 
associated version numbers. File ASDG. MAC is also renamed, but the 
version number is forced to a number one greater than the latest 
version of file ASDG.SMP (assuming a version of ASDG.SMP already 
exists) . 

When you explicitly apply a subswitch to a file specification, you 
implicitly apply the switch with which the subswitch is associated. 
On a command line with more than one file specification, the explicit 
subswitch affects only the file to which it is applied. The implicit 
switch affects all the files on the command line. 



Example 

PIP>FILE1.CMD/GR:R/W0,FILE2.MAC/GR:RW 



This command is equivalent to: 



PI P>F I LE 1 . CMD/GR : R/WO , F I LE 2 . MAC/GR : RW/PR 

The command results in the following file protection: 

a. FILE 1 SYSTEM — Unchanged 

MEMBER — Unchanged 

GROUP — Read access 

WORLD — No access 



b. FILE 2 SYSTEM — Unchanged 

MEMBER — Unchanged 

GROUP — Read/write access 

WORLD — Unchanged 

(For more information on altering the protection level of a file, see 
Section 3.2.2.16.) 
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3.1.3 Wildcards 

PIP allows you to specify wildcards in file specifications. Th* 
wildcard characters are the asterisk (*) and the percent sign (%) 
characters. You can use both wildcards in place of explicit 
specifications for file names, and types and just the asterisk 
wildcard in place of file directories and version numbers. 

The asterisk can denote zero or more characters in the field yo j 
specify it in, while the percent sign character can denote exactly on* 
character in the fields. (Correct syntax must be followed, however. 
See Section 3.1.3.2.) 

Wildcards are restricted in some cases. The following sections 
describe and give examples of wildcards in input and output fil* 
specifications . 



3.1.3.1 Wildcards in Output File Specifications - Wildcards in ths 
output file specifications are restricted. For the following PIP 
functions, the output file specification cannot have any wildcards: 

• Concatenating files to a specified file 

• Appending files to an existing file 

• Updating (rewriting) an existing file 

• Listing a directory 

If you use wildcards in the output file specification for any of thess 
functions, the meaning of the command line would be ambiguous. For 
example :: 

PIP>LIST.*=[200, 200]/LI 

You have incompletely specified the output file specification. PIP 
returns an error message. 

When you make copies of several files, the output specification mus : 
be *.*;* or defaulted from the input file specif ication (s) . 

For the Rename (/RE) and Enter (/EN) switches, the outpu: 
specification may have wildcards (asterisk only) mixed with specified 
fields. For either switch, the equivalent field of the input fils 
specification is used. 

For all cases in which wildcards are allowed in the output file 
specification, the wildcard UFD form [*,*] (but not [n,*] or [*,n]) is 
used to indicate that the output UFD is to be the same as the input 
UFD. 



NOTE 

The percent sign (%) cannot be used in 
output file specifications. 
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3.1.3.2 Wildcards in Input Specifications - PIP provides the 
following wildcard features for input file specifications: 

• *.*;* means all versions of all files. 

• * . DAT ; * means all versions of all files of file type . DAT. 

• *.D*;* means all versions of all files with file types 
beginning with D. 

• TEST.*;* means all versions of all types of files named TEST. 

• T*.*;* means all versions of all types of files with names 
beginning with T. 

• TEST. DAT;* means all versions of file TEST. DAT. 

• TEST. D%T ; * means all versions of files named TEST with 
three-character file types beginning with D and ending with T. 

• T %N . * ; * means all versions of all file types of all 
three-character file names beginning with T and ending with N. 

• *.* means the most recent version of all files. 

• * . DAT means the most recent version of all files of file type 
.DAT. 

• *%.DAT means the most recent version of all files that have at 
least one character in their names and have the file type of 
.DAT. 

• TEST.* means the most recent version of all file types for 
files named TEST. 

PIP also provides the following wildcard UFD features: 

• [***] means all group, member number combinations (1 to 377 
octal) . 

• [nl,*] means all member numbers under group nl. 

• [*,n2] means all group numbers for member n2. 



NOTE 

The percent sign (%) character cannot be 
used in the UFD. 



3.2 PIP COMMAND FUNCTIONS 

PIP copies Files-11 files and performs file control functions. The 
copying function and file control functions are described in the 
following sections. 



3.2.1 Copying Files-11 Files 

To copy Files-11 files, you can enter the PIP command line without 
specifying any switches. 
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The simplest format for the PIP command line is: 

outf ile=inf ile 
outfile 

The output file specification. If the output file name, file 
type, and version are either defaulted or *.*;*, the input file 
name, file type, and version are used for the output file (see 
/NV and /SU subswitches) . If you explicitly specify any portion 
of the output file specification (file name, file type, or 
version) , wildcards cannot be used in this specification. 
Similarly, for a copy command, if you enter any portion of the 
output specification, you can enter only one file as the input 
file. 

inf ile 

The input file specification. If the file name, file type, and 
version fields are not specified, then *.*;* is the default. 

One switch that you can specify when copying Files-11 files is the 
Merge switch. The Merge switch (/ME) creates a new file from two or 
more existing files. PIP assumes /ME when you explicitly specify an 
output file, two or more input files, and no switches. Because the 
basic copy function and the Merge switch are logically related, the 
Merge switch is described here rather than below with the other 
switches . 

The general format of the PIP command line is: 

outf ile=inf ilel [, inf ile2. . . ,inf ilen] [ [/ME] [/subswitch] ] 
outfile 

The output file specification. 



inf ile 

The input file specification. 



/ME 

The Merge switch. 



/subswitch 

Specifies any of the subswitches that you can enter as part of 
the basic command line or with the Merge switch. (Table 3-3 
describes these subswitches.) Subswitches can appear in either 
the output or input file specification. If you place the 
subswitch in an input file specification, it applies only to that 
file. If you place the subswitch in the output file 
specification, it applies to the entire list of input 
specifications. 
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Examples 

1. PI P>DK1 : SAMP. DAT=DK2 : TEST. DAT 

Copies the latest version of file TEST. DAT (in the current 
UFD) from DK2: to DK1:, naming it SAMP. DAT. 

2. PIP>DK1: [*,*] =DK0: [11,*] 

Copies all files from all members in group number 11 of DKO: 

to DK1 : . The files are copied to the same UFD on DK1: that 

they were in on DKO:. Note that the user must have write 
access to all group number 11 UFDs on DK1: . 

3. PIP>LP: =*.LST 

Copies the latest version of all files with a type of . LST in 
the current UFD to the line printer. If the Print Spooler is 
installed on your system, use the /SP switch instead of this 
command. The command line using /SP is in the format: 

PIP>*.LST/SP 

Note that transparent spooling (that is, PI P>LP: «f iles) is 
implemented on RSX-11M-PLUS only. When you specify LPs as 
your output device, the data to be printed is written into an 
intermediate file and then the file is given to the Queue 
Manager, which handles the spooling. Making intermediate 
files allows you to dismount the volume the files are on 
without having to wait until after they have been printed. 

4. PI P>DK1 : SAMP. DAT=DK2 : TEST. DAT ; 1 , NEW . DAT ; 2/ME 

Concatenates version 1 of file TEST. DAT and version 2 of file 
NEW. DAT from DK2: , generating file SAMP. DAT on DK1 : , using 
the current UFD. Note the result would be the same if the 
/ME switch was not specified. 

5. PI P>DK1 : =DB 2: TESTPROG. MAC , . OBJ 

Copies the latest versions of TESTPROG. MAC and TESTPROG. OBJ 
from DB2: to DK1: , using the current UFD for both DB2: and 
DK1: . 

6. PI P>DK1 : =DK0: * . DAT ; * 

Copies all versions of all of the files of file type .DAT in 
the current UFD from DKO: to DK1: . 

7. PIP>DT0: =[200, 10] *.*; * 

Copies all files under [200,10] from the default device (SY: ) 
to DT0: , using the current UFD. 

8. PIP>DP0: [200, 10]=DT0:*.* 

Copies the latest versions of all files from DT0: in the 
current UFD to DP0: [200, 10] . Note that the user must have 
write access to [200,10]. 
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Table 3-3 

PIP Copy Command and Merge Subswitches 



Subswitch 



Description 



/BL:n[. ] 



/CO 



/-CO 



/FO 



Blocks Allocated — This subswitch specifies the 
number of blocks (n) to allocate initially to the 
output file. You can specify n as either an octal 
or decimal value (decimal values must be followed by 
a decimal point) . You can use the /BL:n subswitch 
when you are copying a contiguous file and changing 
its size. 

Contiguous Output — This subswitch specifies that 
the output file be contiguous. When you are copying 
contiguous files from magnetic tape (for example, 
task images) , specify both /CO and /BL:n. You must 
specify /BL:n because PIP cannot determine the 
length of the input file when copying from tape. 
(PIP allocates file space before the copy operation 
is executed. The length of magnetic tape input 
files is on the trailing label for the file.) 

Noncontiguous Output — This subswitch specifies 
that the output file does not have to be contiguous. 

If you do not specify the /BL:n subswitch, the /CO 
subswitch, or the /-CO subswitch, PIP defaults to 
the size and attributes of the input file. 

Set File Ownership — This subswitch specifies that 
the owner of the output file will be the same as the 
output UFD. If you do not specify /FO, the UIC of 
all new files is the UIC under which PIP is running, 
regardless of which directory the files belong to. 
You can use this subswitch with both copy and merge 
commands. 



Examples 

1. If PIP is running under the UIC [1,1], 

DKO: [200, 200]=DK1: [200, 220]TEST. DAT 



creates a new file in the [200,200] directory on 
DKO:, but the file is owned by UIC [1,1]. 



However , 



DKO: [200, 200] =DK1: [200, 220]TEST. DAT/FO 

creates a file owned by UIC [200,200]. When you 
specify /FO, PIP must be running under a UIC 
that has write access to all output directories. 



(continued on next page) 



3-11 



PERIPHERAL INTERCHANGE PROGRAM (PIP) 



Table 3-3 (Cont.) 
PIP Copy Command and Merge Subswitches 



Subswi tch 



Description 



/FO (Cont.) 



DK1: [*, *] /FO=DP0: [13, 10] , [32, 10] , [34, 10] 

Copies all the files from the specified input 
directories to the corresponding directories on 
DK1:. The file owners are the output 
d irectories. 



/SU 



3. DK1: [*,*] =DK0: [*, 10] *.MAC/FO 

Copies all the .MAC files from all group numbers 
with member 10 to DK1: , preserving the UFD and 
setting the file owner for each file to that 
UFD. 

Supersede — This subswitch allows you to copy one 
or more input files to a file whose file name, file 
type, and version may already exist in a UFD. The 
existing file is deleted and a new one is created 
with the data from the input file(s). If the file 
does not already exist, it is created. 

The output file's name, type, and version number 
remain the same, but its file identification number 
(file-ID) may be different. Also, the attributes 
for the output file are taken from the first input 
file and the number of blocks allocated to the 
output file can be different (less than or more 
than) the number of blocks allocated to the existing 
file. 



/NV 



New Version — This subswitch forces the output 
version number of the file being copied to become 
one greater than the latest version of the file 
already in the output directory. If the file does 
not already exist in the output directory, a version 
number of 1 is assigned. Figure 3-1 shows the 
results when you specify /NV. (Specifying /NV is 
not necessary when both the input and output files 
are under the same file directory.) 
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Directories 


Before COPY 






INPUT DIRECTORY 
[201,201] 


OUTPUT DIRECTORY 
[100,100] 






RICK .DAT; 1 


RICK. DAT; 2 
RICK. DAT; 4 






Directories After COPY Without /NV Switch Set 
(version number preserved) 




INPUT DIRECTORY 
[201,2j01] 


OUTPUT DIRECTORY 
[ 






RICK. DAT; 1 


RICK. DAT; 2 
RICK. DAT; 4 
RICK. DAT; 1 




The command used was: 








DKl:[lj0l,l/9jB] = DK2: [201,201] RICK . DAT ; 1 






Directories After COPY With /NV Switch Set 






INPUT DIRECTORY 
[201,201] 


OUTPUT DIRECTORY 
[100,100] 






RICK. DAT; 1 


RICK. DAT; 2 
RICK. DAT; 4 
RICK. DAT; 5 




The command used was : 








DK1 : ( 100, 100 ] = DK1 : [ 201 , 201 ] RICK . DAT ; 1/NV 






NOTE 






The version specified with the /NV sub- 
switch must be explicit or default; no 
wild cards allowed. 
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Figure 3-1 Results of Copy Command With and Without /NV Specified 
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3.2.2 Performing File Control Functions 

PIP provides several switches and subswitches for file control 
processing. These switches and subswitches perform such functions as 
deleting files, displaying the contents of a User File Directory, and 
specifying file protection values. 

You can specify several PIP switches in a command line with no file 
specifications (that is, they may be entered by themselves). These 
switches include /DD, /DF, /ID, and /TD. 

You can specify one or more commands in a line. When using multiple 
commands, the ampersand character (&) separates each command. For 
example : 

PIP>TEST.DAT; 2=SAMP.DAT; 2/SU, SAMP. DAT ; 1 &TEST . DAT ; */FU&SAMP. DAT/PU/LD 

1. PIP merges SAMP. DAT; 2 and SAMP. DAT; 1 into TEST. DAT; 2. The 
/SU subswitch causes TEST. DAT • s file name, file type, and 
version number to remain the same, but TEST.DAT;2's contents 
are replaced with the input file's contents. 

2. The /FU switch causes PIP to do a full format listing of all 
versions of the file TEST. DAT. 

3. The /PU switch causes PIP to purge SAMP. DAT and the /LD 
subswitch causes PIP to list the deleted files. 

The values that you specify with the switches and subswitches default 
to octal. You can specify decimal values by adding a decimal point 
after the value. 



3.2.2.1 /AP — Append Switch - The Append switch (/AP) opens an 
existing file and appends the input file(s) to the end of it. Specify 
the /AP switch in the following format: 

outfile=infilel[,infile2...,infilen] /AP[/FO] 

outf ile 

The output file specification. Wildcard specifications are not 
allowed in the output file specification. The file type and the 
record attributes for the output file remain the same after the 
input file(s) have been appended to it. The file name and file 
type for the output file must be specified explicitly. 



inf ile 

The input file specification. If the file name, file type, and 
version are not specified, then *.*;* is the default. 



/AP 

The Append switch. 
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/FO 

The Set File Ownership subswitch, which specifies that the owning 
UIC of the output file is the same directory to which the input 
file belongs. If you do not specify /FO, the owning UIC of the 
output file is unchanged, regardless of which directory the input 
files belong to. See Section 3.2.1 for examples of using /FO. 



Example 

PI P>DK1: FILE 1. DAT ;1=FILE 2. DAT ;1, FILE3.DAT; 1, FILE 4. DAT; 1/AP 

Opens FILE1. DAT; 1 on DK1: and appends the contents of 
F I LE 2 . DAT ; 1 , FILE 3. DAT; 1 and FILE 4. DAT; 1 to it. 

Note that if the output file is contiguous before the appending, 
it may not be contiguous afterwards. 



3.2.2.2 /BS:n — Block Size Switch - The Block Size switch (/BS:n) 
defines the block size for magnetic tapes. This switch allows you to 
read or write bigger blocks onto magnetic tape, thereby saving some of 
the sp>ace taken by interrecord gaps. The default block size is 
512(10) bytes per block. Specify the /BS switch using the following 
format : 

outf ile/BS:n=inf ile 



outf ile 

The output file specification. 



/BS:n[. ] 



The Block Size switch, where n is an octal or decimal number 
specifying the number of bytes in a block. 



inf ile 

The input file specification. 

The /BS switch specifies the block size of the output file. If the 
block size specified is smaller than the actual block size, an I/O 
error occurs. 



Example 

PIP>MT:BA.DOC/BS: 204 8. =AMBER. DOC 

This command increases the block size of the output file, BA.DOC, 
to 2048(10) bytes per block. 
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3.2.2.3 /CD — Creation Date Switch - The Creation Date switch (/CD), 
used in a file transfer command, allows the output file to take the 
date on which the input file was created rather than the date of 
transfer. You cannot use this switch with the explicit or implicit 
Merge switch (/ME) and/or with an output magnetic tape device. 
Specify the /CD switch in the following format: 

outf ile/CD=inf ilel [,infile2. . . ,infilen] 

or 

outf ile=in file 1/CD[, infile2. . . ,infilen] 
outf ile 

The output file specification, 
inf ile 

The input file specification. 

/CD 

The Creation Date switch. 
Example 

PIP>/LI 

DIRECTORY DB 1 : [ 200 , 200 ] 
21-NOV-80 14:02 

F ILE . DAT ; 7 12. 6-OCT-80 16:13 

PI P>TEST. DAT/CD=FILE . DAT/LI 

DIRECTORY DB 1 : [ 200 , 200 ] 
21-NOV-80 14:05 

FILE. DAT; 7 12. 6-OCT-80 16:13 

TEST. DAT ; 1 12. 6-OCT-80 16:13 

The command creates a new file, TEST. DAT, from FILE. DAT and gives 
it the creation date of FILE. DAT rather than the transfer date. 

3.2.2.4 /DD — Default Date Switch - The Default Date switch (/DD) 
restricts file searches to files created during a specific period of 
time. Specify the /DD switch in the following format: 

/DD: startdate :enddate 

/DD 

The Default Date switch 
startdate 

The beginning date of the specified time period in the form 
dd-mm-yy. May be unlimited by using the wildcard character (*) . 
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enddate 

The ending date of the specified time period in the form 
dd-mm-yy. May be unlimited by using the wildcard character (*) . 

Specifying the wildcard for both startdate and enddate negates the /DD 
switch: 

/DD:*:* 

The date restrictions for the file searches are now disabled. 
Examples 

1. PIP>/DD: 01-JUN-80: 01-JUL-80/LI 

Lists all files created from 1 June 1980 through 1 July 1980. 

2. PIP>/DD:*: 1-JUN-80/LI 

Lists all files created on or before 1 June 1980. 

3. PIP>/DD: l-JUN-80: */LI 

Lists all files created on or after 1 June 1980. 



3.2.2.5 /DE — Delete Switch - The Delete switch (/DE) deletes files 
from a UFD. Optionally, you can specify that the deleted files be 
listed on your terminal. Specify the /DE switch in the following 
format :: 

inf ilel [,inf ile2. . . , inf ilen] /DE [/LD] 
inf ile 

The input file specification. 

/DE 

The Delete switch. 

/LD 

The List Deleted files subswitch. 

You must specify a version number or a wildcard in its place when 
using the Delete switch. 

Use a version number of ;-l to specify the oldest version of a file. 
Use a version number of ;0 or ; to specify the most recent version. 

Examples 

1. PIP>TEST.DAT;-1/DE 

Deletes the oldest version of file TEST. DAT. 

2. PIP>TEST1.DAT; 0, TEST2. DAT ; /DE 

Deletes the latest version of files TEST1.DAT and TEST 2. DAT. 
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Wildcards in the file name or file type fields are illegal when a 
version of ;-l, ;0, or ; is specified. 

You must issue the file specification because an unspecified file 

name, file type, and version does not default to *.*;*. 

The input file specification can take all the usual forms, including 
wildcards (even in [ufd]). The only special requirement is that the 
version field must always be specified. 



Examples 

1. PIP>TEST.DAT; 5/DE 

Deletes version 5 of file TEST. DAT from the current default 
directory on the default device. 

2. PIP>TEST.DAT;1, ;2/DE 

Deletes versions 1 and 2 of file TEST. DAT from the current 
default directory on the default device. 

3. PI P>* . OB J; * , * . TMP; */DE/LD 

Deletes all versions of all files of the file type .OBJ and 
.TMP from the current default directory on the default 
device. Lists all deleted files of both file types. 

4. PIP>*.OBJ;*/LD,*.TMP; */DE 

Deletes all versions of all files of the file type .OBJ and 
.TMP from the current default directory on the default 
device. Lists all deleted files of both file types. 



3.2.2.6 /DF — Default Switch - The Default switch (/DF) changes the 
default device and/or UFD for the current PIP task. 

The usual default device of PIP is the user's system device (SYO: ) . 

The usual default UFD is the UIC under which PIP is currently running. 
The /DF switch alters only the default UFD. It does not affect the 
UIC under which PIP is running, nor does it circumvent file 
protection. 

Specify the /DF switch in one of the following formats: 
dev: [ufd] /DF 
or 

dev :/DF 
or 

[ufd]/DF 
or 

/DF 
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dev: 

If specified, the new default device to be applied to subsequent 
PIP command lines. 

[ufd] 

If specified, the new default UFD to be applied to subsequent PIP 
command lines. 

/DF 

The Default switch. 

The /DF switch specified with no arguments returns the default device 
to the user's system device (SYO: ) and the default UFD to the UIC from 
which PIP was invoked. 

Examples 

1. PIP> [27, 27] /DF 

Sets the default UFD to [27,27]. 

2. PIP>DK1:/DF 

Sets the default device to DK1:. 

3. PIP>DK1: [27, 27]/DF 

Sets the default device to DK1: and the default UFD to 
[27, 27] . 

4. PIP>/DF 

Returns the user's default device to SYO: and the default 
UFD to the UIC from which PIP was invoked. 



3.2.2.7 /EN — Enter Switch - The Enter switch (/EN) lets you enter a 
synonym for a file in a directory or directories on the same device. 
This allows the file to be accessed by more than one name. Also 
provided is a subswitch, New Version (/NV) , which forces the version 
number of the file being entered into the directory to a number one 
greater than the latest version of the file. Specify the Enter switch 
in the following format: 

outfile=infilel[,infile2...,infilen] /EN [/NVj 



outf ile 



The file specification of the new directory entry. The output 
file specification has a special property in that the file name, 
file type, or version may be explicit, wildcard (*) , or 
defaulted. A file name, file type, or version field that is 
either wildcard (*) or default (null) means that the 
corresponding field of the input file is to be used. 

infile 



The file specification for the input file in the format: 
dev : [ufd] filename .filet ype ; version/EN [/NV] 
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If you specify a device in either the input or output file 
specification, that device sets the default for the other side. 
If you do not specify a device on either the input or output 
side, the current default device is assumed to be the default 
device. If both the input side and the output side explicitly 
reference different devices, PIP returns an error message that 
requests that the line be reentered. 

The default input file specification is *.*;*. 

/EN 

The Enter switch. 

/NV 

The New Version subswitch. The /NV subswitch may appear on 
either side of the equal sign. If it appears on the output side, 
all of the files being entered are forced to a version number one 
greater than the latest version of the file. If it appears on 
the input side, only files that have the /NV subswitch appended 
to them are forced to a number one greater than the latest 
version. (Specifying the /NV subswitch is not necessary when 
both the input and output files are under the same file 
directory. ) 



Example (see Figure 3-2) 

PIP>[101, 101]TWIG/EN=[200, 200 ] RICK. DAT; 1 



Before 



DIRECTORY [200,200] 


DIRECTORY [101,101] 


RICK. DAT ;1 


JEN. OB J; 2 
LAU.OBJ;3 



After 



DIRECTORY [200,200] 


DIRECTORY [101,101] 


RICK. DAT ;1 


JEN. OBJ; 2 
LAU . OBJ ; 3 
TWIG. DAT; 1 



NOTE 



The directory items for RICK. DAT; 1 and 
TWIG. DAT; 1 both reference the same file. 
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Figure 3-2 Sample Directories Before and After Execution 
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3.2.2.8 /EOF — End-of-File Switch - The End-of-File switch (/EOF) 
allows you to specify where the file's end-of-file will be. This 
helps in certain situations (for example, system crashes) when a file 
contains useful information but its EOF pointers are wrong, preventing 
you from obtaining the information. 

EOF is an unprotected file attribute. If you are the file owner or 
have a system-level UIC, you do not need read or write access to read 
or change this attribute. If you are classified group or world to the 
file owner's UIC, you need read access to read the attribute and write 
access to change it. 

Specify the /EOF switch in the following format: 

infil el/EOF [: block :byte] [, . . . inf ilen/EOF [: block :byte] ] 
infile 

The input file specification. 

The file specification must be issued because an unspecified file 
name, file type, and version do not default to *.*;*. 

block 

The block number where the EOF pointer is to be placed. Usually, 
the EOF pointer cannot be placed beyond the highest number of 
blocks allocated to the file. However, if all the bytes of the 
allocated blocks are used, the EOF pointer can be placed in the 
first byte of the next block (/EOF: blocks allocated plus 
one:0). The block number can be octal or decimal. 

byte 

The byte location of EOF is the first unused byte of the 
specified block. The byte number can be octal or decimal. The 
maximum value for byte is 777(8). 

If you do not enter either of the values for block and byte, PIP 

places EOF past the last byte of the last block allocated to the file. 

If you specify a value for either block or byte that is greater than 

the maximum value allowed, PIP returns an error message. 

Note that the /EOF switch is local to each file specification and 
therefore does not default from left to right. 

Example 

PI P>A.TMP/EOF: 17: 253, AA. TMP/EOF 
is equivalent to 

PI P>A. TMP/EOF: 17: 253, AA. TMP/EOF : 23: 

where the file AA.TMP has 22 blocks allocated. 



3.2.2.9 /EX — File Exclusion Switch - The File Exclusion switch 
(/EX) excludes one file specification's worth of files during file 
searches. You can exclude any field in the file specification. The 
fields can have in them characters and/or wildcards. Specify the /EX 
switch in the following format: 

f ilespec/EX 
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f ilespec 

The file specification. The file name and/or the file type 
and/or the version number can be a wildcard, but not all three 
fields. Also, you cannot specify devices or UFDs. 

/EX 



The File Exclusion switch. 



Specifying the /EX switch by itself negates it. 



PIP>/EX 
Example 

PI P>*.CMD; */EX/LI 



DIRECTORY DB1: [301,7] 
8-JUL-81 14:50 
*.CMD;*EXCLUDED 



EXECM.MAC;23 45. 23-FEB-80 14:23 

RUN.TSK;46 5. 29-OCT-80 11:59 

FRANK. OBJ; 16 33. 02-MAY-80 13:58 

DEBBIE. COR;2 5.0. 14-JAN-81 12:01 



Excludes all files of the type .CMD from the search done in 
*.*; */LI. 



3.2.2.10 /FI — File Identification Switch - The File Identification 

switch (/FI) allows you to access an existing file by its file 

identification number (File-ID). Specify the /FI switch in the 
following format: 

outf ile=/FI:f ilenum :seqnum 

/FI 

The File Identification switch, 
f ilenum 

The file number, 
seqnum 

The sequence number of the file. 

The file identification number (file-ID) is assigned by RSX-11 when 
the file is created. To find the file identification number of a 
file, use the Full List switch (/FU) . The /FU switch displays the 
file identification and sequence numbers and other information 
describing the file. 



Examples 



1. You can use the /FI switch to create a directory entry for a 
file. 



PI P>XYZ . TSK=/FI : 301 : 27/EN 
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2. You can copy a file using the /PI: switch. 

PIP>A.B=/FI: 301: 27 

3. To list entries in the directory file whose file 
identification is 1275,47, use the /FI switch in the format: 

PIP>/FI: 1275: 47/LI 



DIRECTORY DR2: FILE ID 001275,000047,0 
8-AUG-81 15:58 

MCR.CMD 1. 29-NOV-80 13:22 

DCL.CMD 1. 29-NOV-80 13:24 



3.2.2.11 /FR — Free Switch - The Free switch (/FR) 
amount of available space on a specified volume, 
contiguous space on that volume, the number of available 
and the number of file headers used. Specify the /FR 
following format: 

[dev: ]/FR 

If you do not specify dev:, PIP defaults to SY0:. 

The format of the information from the /FR switch is shown below. 

dev: HAS xxxx. BLOCKS FREE, yyyy. BLOCKS USED OUT OF zzzz. 
LARGEST CONTIGUOUS SPACE = nnnn. BLOCKS 

aaaa. FILE HEADERS ARE FREE, bbbb. HEADERS USED OUT OF cccc. 

Usually, the number of free file headers corresponds to the number of 
files that can be created. However, fragmented files and files that 
are too large for one file header must be allocated more than one file 
header . 

The number of file headers will not exceed the number of files that 
can be created. 



Example 

PIP>db7:/FR 

DB7: HAS 10662. BLOCKS FREE, 330008. BLOCKS USED OUT OF 340670. 
LARGEST CONTIGUOUS SPACE = 4189. BLOCKS 

9025. FILE HEADERS ARE FREE, 11931. HEADERS USED OUT OF 20956. 



3.2.2.12 /ID — Identify Switch - The Identify switch (/ID) 
identifies the version of PIP being used. Specify the /ID switch in 
the following format: 

/ID 

When you specify this switch, the version number is listed on the 
input terminal as follows: 

PIP VERSION Mvvee (ANSI) 



displays the 
the largest 
file headers, 
switch in the 
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vv 

The version number. 

ee 

The edit number. 
(ANSI) 

If PIP is linked to an ANSI FCS, this field will appear. 
Otherwise, it is blank. 

NOTE 

For ; ;JtBX~ilM\0perai$iiig $y&tem&, if you 
:> ANEI .^magnetic'- . - tape support, PIP 
■$$•£ \tm-'iittift ' Mthr MIUB. 'instead of 

Example 

PIP>/ID 

PIP — PIP VERSION M1340 (ANSI) 

3.2.2.13 /LI — List Switch - The List switch (/LI) lists one or more 
files contained in a UFD, along with their status information. Three 
alternate mode subswitches (/BR, /FU, and /TB) allow you a choice of 
directory listing formats. Table 3-4 describes these switches. 
Specify the /LI switch in the following format: 

[listfile=]infilel[,infile2..., inf ilen] /LI [/subswi tch] 

listf ile 

The file specification to be listed in the format: 

dev: [ufd] f ilename.f iletype ; version 
If listfile is not specified, it defaults to TI:. 
inf ile 

The input file specification in the format: 

dev: [ufd] f ilename.f iletype /version 
The default for infile is *.*;*. 

/LI 

The List switch. This switch lists the following information: 

1. f ilename.f iletype ; version 

2. number of blocks used (decimal) 
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3. file code: 

(null) = noncontiguous 
C = contiguous 
L = locked 

4. creation date and time 

5. summary line, which includes the number of blocks 
used/allocated and files printed. 

/subswitch 

The alternate mode subswitch of the List switch (described in 
Table 3-4) . 



Table 3-4 
List Subswitches 



Subswitch 


Description 


/BR 

/FU[:n[.]J 


Specifies the brief form of directory listing. This 
switch lists only the file name, file type, and 
version . 

Specifies the full directory format. 

Because the /FU format uses protected file 
attributes, you may need read access to get a full 
directory listing of a file. If you are the file 
owner or have a system-level UIC, you do not need 
read access. If you are classified group or world 
to the file owner's UIC, you need read access to 
read the protected attributes of the file. (To 
change the protection level attribute, see Section 
3. 2. 2. 16. ) 

If specified, n is the number of characters per 
line. If not specified, the number defaults to the 
buffer size of the output device. 

The /FU switch lists the following information: 

1. f ilename,f iletype ;version 

2. file identification number in the format: 
(file number, file sequence number) 

3. number of blocks used/allocated (decimal) 



(continued on next page) 
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Table 3-4 (Cont.) 
List Subswitches 



Subswi tch 


Description 


/FU[:n[.]] 
(Cont.) 


4. 


file code: 

(null) = noncontiguous 
C = contiguous 
L = locked 




5. 


creation date and time 




6. 


owner UIC and file protection in the format: 

[group, member] [system , owner ,g roup , wo rid] 

These protection fields can contain the values 
R, W, E, or D. 

where : 

R = Read access permitted 
W = Write access permitted 
E = Extend privilege permitted 
D = Delete privilege permitted 




7. 


date and time of the last update plus the number 
of revisions. 




8. 


summary line, which contains the number of 
blocks used, the number of blocks allocated, and 
the number of files used. 


/TB 


This switch only outputs the summary line in the 
following format: 






TOTAL OF nnnn. /mmmm. BLOCKS IN xxxx. FILES 




where : 






nnnn = blocks used 
mmmm = blocks allocated 
xxxx = number of files 



Figure 3-3 contains sample directory listings in the various formats. 



3-26 



PERIPHERAL INTERCHANGE PROGRAM (PIP) 



Total Blocks (/TB) Format 



STORAGE USED/ALLOCATED FOR DIRECTORY DK2 J C200 r 2703 
15-JUL-75 15 J 46 



TOTAL OF 145./150. BLOCKS IN 5. FILES 



Brief (/BR) Format 



DIRECTORY DK2t C200»2703 



CKTST.MACI6 
IOTST.MACM 
I0TST.T8M1 
CKTST.T8KH 
CKTST.MACI7 



Standard (/LI) Format 



DIRECTORY DK2:C200 


»270D 






15-JUIL-75 15 J 46 








CKT6T.MACI6 


3* 


15-JUL-75 


15:39 


I0TST.MAO4 


4* 


15-JUL-75 


15139 


I0T8T.T8KK 


69* 


C 15-JUL-75 


15t39 


CKT8T.TSM1 


69. 


C 15-JUL-75 


15M0 


CKTST.HACI7 


0. 


L 15-JUL-75 


15*40 



TOTAL OF 145* BLOCKS IN 5* FILES 



Full (/FU) Format 



DIRECTORY DK2 * C 200, 2703 
15-JUIL-75 15: 46 



CKT8T.HACI6 


(10,10) 


3./3. 




15- JUL 


-75 


C200r270KRWED 


, RUED, RUED, R 3 












IOTST.MACM 


(11,11) 


4./4. 




15- JUL 


-75 


C200f 270DCRWED 


, RUED, RUED, R3 












IOTST.TSKH 


(7rl2) 


69. /69. 


C 


15- JUL 


-75 


C 200, 270 3 C RUED 


, RUED, RUED rR 3 












CKTST.TSKH 


(12,13) 


69. /69. 


C 


15- 


JUL 


-75 


C200r2703CRWED 


rRUEDr RUED, R3 












CKTST.MA07 


(13,14) 


0./5. 


L 


15- 


JUL 


-75 


C200»2703CRWED 


, RUED, RUED, R 3 












TOTAL OF 


145. /ISO. BLOCKS 


IN 5. FILES 











ZK-176-81 

Figure 3-3 Directory Listing Examples 
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Examples 

1. PIP>/LI 

Lists the directory of the current default device and 
directory. (This is equivalent to TI :=*.*; */LI . ) 

2. PIP>LP: =[*,*] /FU: 132. 

Lists on the line printer in full format (132-column 
listing), all of the directories on the current default 
device . 

Note that only RSX-11M-PLUS has transparent spooling (see 
Examples, Section 3.2.1). 

3. PI P>TI : =TEST. DAT/FU 

Lists on TI: the full directory listing for the latest 
version of TEST. DAT in the current default device and 
directory. 

4. PIP>JUL13.DIR=[200, 200] *.*/LI 

Lists the latest version of all files in directory [200,200] 
on the current default device to file JUL13.DIR in the 
default directory on the default device. 

5. PIP>LP:=[11,*] *.CMD;*/LI 

Lists on the line printer all versions of all files with the 
file type .CMD in all directories in group 11. 

Note that only RSX-11M-PLUS has transparent spooling (see 
Examples, Section 3.2.1). 

6. PIP>LP:/BR=[11, 11] *. CMD;*,*. DAT;*, *.MAC;1 

Lists on the line printer in brief format all versions of all 
files with a file type of .CMD, all versions of all files 
with a file type of .DAT, and all files of file type .MAC 
with a version number of 1. These files all reside in the 
directory [11,11] on the current default device. 

Note that only RSX-11M-PLUS has transparent spooling (see 
Examples, Section 3*2,1). 



3.2.2.14 /ME — Merge Switch - The Merge switch (/ME) creates a 
single file from two or more existing files. The /ME switch is used 
in copying Files-11 files and is described in Section 3.2.1. 



3.2.2.15 /NM — No Message Switch - The No Message switch (/NM) 
suppresses the PIP error messages, NO SUCH FILES (S) and FILE NOT 
LOCKED, when you are manipulating files. Specify the /NM switch in 
the following format: 

infilel[,infile2,...infilen] [/sw] /NM 



3-28 



PERIPHERAL INTERCHANGE PROGRAM (PIP) 



infile 

The input file specification. 

/sw 

Any combination of appropriate switches and subswitches, for 
example, the /LI, /DE, /PU, or /UN switches and any of their 
respective subswitches. 

/NM 

The No Message switch. 

The /NM switch applies not only to the file specification 
preceding it, but also to all file specifications to the right of 
it. 



Example 

PI P> * . MAC ; */NM , TEST . DAT ; 1 , FI LE S . OB J ; */DE 

If none of these files exists in the default directory, you will 
not get the error message, NO SUCH FILE(S), when PIP tries to 
delete them. 



3.2.2.16 /PR — Protect Switch - The Protect switch (/PR) allows you 
to set the protection status of a file. File protection is provided 
for four categories: 

System 

Specifies which categories of access the system UICs are allowed 
to the file (that is, UICs with group numbers less than or equal 
to 10 octal) . 

Owner 

Specifies which categories of access the owner has allowed. 

Group 

Specifies which categories of access other members in the same 
group have. 

World 

Specifies categories of access given all other UICs. 

For each category, you can specify whether that category can read, 
write, extend, or delete the file. To alter the protection level of a 
file, you can use either the /PR subswitches (/SY, /OW, /GR, /WO) or 
octal representation (/PR:n) . For either method, if you are the file 
owner or have a system-level UIC, you can alter the protection level 
without having read or write access. However, because the protection 
level of a file is a protected attribute, you cannot alter the 
protection level if you are group or world to the file owner's UIC. 
(You can read protected attributes if you have read access.) 
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Specify the /PR switch in the following format: 

infile/PR[/SY[:RWED]] [/OW[:RWED]] [/GR [ : RWED] ] [/WO[:RWED]] [/FO] 



inf ile 

The file specification for the file whose protection is being 
changed in the format: 

dev: [ufd] f ilename.f iletype ;version 

File specification must be issued because an unspecified file 
name, file type, and version do not default to *.*;*. 



/PR 

The Protect switch. 



/SY r /OW,/GR, and /WO 

The subswitches that specify protection level for a file. These 
subswitches specify which protection level is to be altered 
(others are left intact) . The values that follow the switch are 
any of the four letters, R, W, E, and D (for read, write, extend, 
and delete) , in any order. They specify which privileges the 
respective categories can have. If you enter the subswitch and 
do not specify a value, no privileges are granted for that 
category. 

The subswitches are identified as follows: 

/SY is the System subswitch. 
/OW is the Owner subswitch. 
/GR is the Group subswitch. 
/WO is the World subswitch. 

Protection can also be specified by an optional octal value on 
the /PR switch, in the format: 

/PR:n 

The variable n is the octal representation of the protection to 
be assigned to the file. This octal number is taken as the new 
protection word. (See the RSX-11M or RSX-11M-PLUS Mini-Reference 
Manual for the list of octal codes.) The format of the protection 
word is shown in Figure 3-4. 



/FO 

The Set File Ownership subswitch, which allows you to set the 
ownership of a file to that of the UIC of the directory in which 
it is entered. (You can change the file ownership at the same 
time you set the protection value.) If there are files in the 
[200,200] directory that are owned by another UIC, the command 

PIP> [200, 200] *.*; */PR/FO 

causes all files to be owned by [200,200] without changing their 
protection . 
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15 12 11 8 7 4 3 


P 


D r-i-i*-o /-•+■ i r\r\ WORT n rDnilP HUTWCD CVCTTTM 


J 


word 




yi i o ^ 




D E W R 




(bit set means NO access permitted.) 




Example 




TEST.DAT;5/PR:3 




(bits & 1 set) 




deny write and read access to the system 




for file TEST. DAT; 5. 
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Figure 3-4 Format of Protection Word 



Examples 

1„ PIP>TEST.DAT; 5/PR/OW : RWE/GR : RWE/WO 

Sets the protection level so that the owner and group have 
RWE privileges (not delete) , world has no access privileges, 
and system privileges are unchanged. 

2„ PIP>[*, *]*.*; */PR: 

Sets the protection level of all files so that all categories 
are granted all access privileges. 

3. PIP>DK0: [*,*]*.*; */PR/FO 

Causes all file owners to be the same UIC as the UFD in which 
the files are entered. 



3.2.2.17 /PU — Purge Switch - The Purge switch (/PU) deletes a 
specified range of obsolete versions of a file. Optionally, you can 
specify that the names of deleted files be listed on your terminal. 

Specify the /PU switch in the following format: 

inf ilel [,inf ile2. . . , inf ilen] /PU [ :n] [/LD] 

infile 

The file specification for the file(s) to be deleted. The file 
specification takes the form: 

dev: [ufd] f ilename.f iletype 

Note that a version number is not needed. If specified, it is 
ignored . 
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/PU[:n[.]] 

The Purge switch. If you specify the optional value n and the 
latest version of the file is m, then all existing versions less 
than or equal to m-n are deleted (see Figure 3-5) . Although it 
is useful to think of this command as deleting all but the n most 
recent versions, it is important to understand that if any 
versions are already deleted between m-n and m, fewer than n 
versions will be retained. The most recent version of the file 
is always retained. 

If you omit the value n f PIP defaults to 1, and all but the 
latest version of the file are deleted. If n is greater than the 
number of versions of the specified files, no files are deleted. 

The value n is local and defaults from left to right. This means 
that if you specify n at the end of the command line, it only 
applies to the infile immediately preceding it. All other 
infiles default to one. However, n applies to all following 
infiles until you make a new specification for n. 

/LD 

The List Deleted files subswitch. 



Examples 

1. PIP>*.OBJ,*.MAC/PU: 2/LD 

Deletes all but the highest version of all files with a file 
type of .OBJ, and all but the two highest versions of all 
files with a file type of .MAC. Lists all deleted files. 

2. PIP>*.OBJ/PU: 2/LD,*. MAC 

Deletes all but the two highest versions of all files with 
file types of .OBJ and .MAC. Lists all deleted files. 



Directory Before Purge Directory After Purge 




GARY ; 1 




GARY; 3 






GARY; 2 




GARY ; 4 






GARY ; 3 




GARY ; 5 






GARY ; 4 


GARY/PU : 3 , RICK/PU : 2 


RICK; 7 






GARY ; 5 








RICK; 4 










RICK; 5 










RICK ; 7 








In the case of the files named GARY, the three latest versions (3, 4, and 5) 
are retained; versions 1 and 2 are deleted. In the case of the files named 
RICK, since version 6 did not exist, only version 7 is retained; and all 
existing versions less than or equal to 5, for example, versions 4 and 5, 
are deleted. 
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Figure 3-5 Use of the Purge Switch 
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3.2.2.18 /RE — Rename Switch - The Rename switch (/RE) changes the 

name of a file. There is also a New Version subswitch (/NV) that 

forces the renamed file to have a version number one greater than the 

latest version of the previously existing file with the same name (see 

Figure 3-6) . Note that you cannot rename a file that is copied from 
one device to another device. Specify the Rename switch in the 
following format: 

outfile=infilel[,infile2... , inf ilen] /RE [/NV] 

outf ile 

The file specification to be given to the new file. The output 
file specification has a special property in that the file name, 
file type, and version are each allowed to be explicit, wildcard 
(*) , or defaulted (null). A UFD, filename, filetype, or version 
field that is either wildcard (*) or defaulted (null) means that 
the corresponding field of the input file is to be used. Thus, 
the Rename switch can change one or more fields while preserving 
the others. The output file specification takes the following 
form : 

dev: [ufd] filename. filetype /version 

infile 

The file specification of the file to be renamed. The input file 
specifications are standard and allow wildcards in all fields, 
including UFD. The input file specification takes the following 
form : 

dev: [ufd] fi lename . fi letype /version 

An unspecified file name, file type, and version defaults to 

* * . * 
• i • 

The /RE switch does not transfer data. The file is entered in 
the new directory and deleted from the old directory. The 
directories must be on the same device because data is not 
transferred. You can move files out of one directory into 
another, preserving the file name, file type, and version, or 
changing them if desired. (This is permitted only if PIP is 
running under a UIC with write privileges for each of the 
directories involved.) 

If you specify a device on either the input or output side, that 
device sets the default for the other side. If both the input 
side and the output side explicitly reference different devices, 
PIP returns an error message and requests that you reenter the 
1 ine . 

/RE 

The Rename switch. 
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/NV 

The New Version subswitch. The /NV subswitch forces the version 
number of the renamed file to a number one greater than the 
latest version for the file. 

The /NV subswitch may appear on either side of the equal sign. 
If it appears on the output side, all of the version numbers of 
files being renamed are forced to a number one greater than the 
latest version for the file. If it appears on the input side, 
only the file that has the subswitch appended to it has its 
version number forced to one greater than the latest version of 
the file. (Specifying /NV is not necessary when both the input 
and output files are under the same directory file.) 

Examples 

1. PI P>TESTFILE. DAT; 1=TEST. DAT; 5/RE 
Renames TEST. DAT; 5 to TESTFILE . DAT; 1. 

2. PIP>BACKUP.*; *=TEST.*; */RE 

Renames all versions of all files with file names TEST to 
BACKUP, preserving the file type and version of each file. 

3. PIP>*.*; 1 = *.*; */RE 

Renames all copies of all files to version 1. 

4. PIP>[200, 220]= [200, 200]/RE 

Renames all files from [200,200] to [200,220], preserving the 
file name, file type, and version of each file. 

5. PIP>EXAMPLE.*; *=TEST.*; */RE 

Renames all versions of all files with the file name TEST to 
the file name EXAMPLE, preserving the file type and version 
of each file. 

6. PI P>SAVE . DAT/RE/N V=OUTPUT . DAT ; 1 

Renames OUTPUT. DAT; 1 and forces the version number to one 
greater than the latest version of SAVE. DAT. Figure 3-6 
illustrates the results with and without the /NV switch. 
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Directory Before Rename 

SAVE. DAT; 2 
SAVE. DAT; 3 
SAVE. DAT; 4 
OUTPUT.DAT; 1 
OUTPUT.DAT; 2 

Directory After Rename Without /NV Switch Set 

SAVE. DAT; 2 
SAVE. DAT; 3 
SAVE. DAT; 4 
SAVE. DAT; 1 
OUTPUT.DAT; 2 

Directory After Rename With /NV Switch Set 

SAVE. DAT; 2 
SAVE. DAT; 3 
SAVE. DAT; 4 
SAVE. DAT; 5 
OUTPUT.DAT; 2 

ZK- 179-81 

Figure 3-6 Results of Rename Switch With and Without /NV Specified 



3.2.2.19 /RM — Remove Switch - The Remove switch (/RM) removes an 
entry from a UFD, but does not delete the file associated with that 
entry. The Remove switch is particularly useful for deleting 
directory entries which, for whatever reason, point to nonexistent 
files. It is also used to delete synonyms generated by the Enter 
switch. If the last entry for an existing file is removed, that file 
can be located only by using the VFY utility with its /LO switch (see 
Chapter 9). Specify the /RM switch in the following format: 

infilel[,infile2...,infilen] /RM 

inf ile 

The file specification for the directory file entry to be 
removed. The file specification takes the form: 

dev: [ufd] f ilename.f i letype-; version 

The file specification must be issued because a null file name, 
file type, and version do not default to *.*;*. 

/RM 

The Remove switch. 



Example 

PIP>DK1: [10, 10]RICKSFILE.DAT;1/RM 

Removes the file entry RICKSFILE . DAT; 1 from the directory [10,10] 
on DK1 : . 
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3.2.2.20 /RW — Rewind Switch - The Rewind switch (/RW) directs PIP 
to rewind magnetic tape. (The /RW switch cannot be used for 
DECtapes.) You can apply this switch to both input and output 
specifications. When you specify the /RW switch with the output 
specification, PIP begins writing the file at the beginning of the 
tape. You can use this technique to erase a tape before writing files 
on it. Specify the /RW switch in the following format: 

outf ile/RW=inf ile 

or 

outf ile=inf ile/RW 
outf ile 

The output file specification, 
infile 

The input file specification. 

/RW 

The Rewind switch. 

When you apply the /RW switch to the input specification, it rewinds 
the tape before searching for the input file. The magnetic tape 
processor performs the following process when it searches for a file 
to open: 

1. Searches from the current position to end of tape 

2. Rewinds the tape 

3. Searches from the beginning of tape to the point where search 
processing began 

You can use /RW with the input specification to save search time. If 
you know a file is behind the tape's current position, /RW rewinds the 
tape before searching for the file to open. This saves the time that 
otherwise would have been taken to search for the file between the 
current position and the end of the tape. 



Example 

PIP>MT:/RW=[200, 200] 

Starts the beginning of the tape and outputs all files in the 
directory [200,200]. 

PI P>AMBER . DOC=MT: AB . DOC/RW 

Rewinds the tape, then searches the tape for the file AB.DOC and 
outputs the file renaming it AMBER. DOC . 
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3.2.2.21 /SB — Span Blocks Switch - The Span Blocks switch (/SB) 
allows you to control whether records copied from magnetic tape to 
disk will cross block boundaries. If you omit this switch, the file 
is copied with records possibly crossing block boundaries. If you 
specify /-SB, the records will not cross block boundaries. 

Specify the Span Blocks switch in the following format: 

outdsk :outf ile/SB=inmag : inf ile 
outf ile 

The disk output file, 
inf ile 

The magnetic tape input file. 

/SB 

The Span Blocks switch. 



Example 

PI P>DK1: FILES. DAT/-SB=MM0: FILES. DAT 

Copies FILES . DAT records to the disk from magnetic tape. Records 
on the disk will not cross block boundaries. 



3.2.2.22 /SD — Selective Delete Switch - The Selective Delete switch 
(/SD) prompts for your response before deleting a file that you have 
specified in the command line for deletion. The response choices are 
carriage return (<RET>) or control-Z (~Z) , or Y, N r G, or Q, each 
followed by either a carriage return (<RET>) or control-Z (~Z) . Table 
3-5 describes the effect of each combination of letter and terminator. 

Specify the /SD switch in the following format: 



infilel[,infile2...,infilen] /SD 
inf ile 

The input file specification in the form: 

dev: [ufd] f ilename.fi letype ; vers ion 

The file specification must be issued because a null file name, 
file type, and version do not default to *.*;*. 



/SD 

The Selective Delete switch. 
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Table 3-5 

Response Choices for the Selective Delete Switch 



Letter 


Terminator 


Operation 


y 




Dpi php f hi ? f i "I ^ anH nnnfinup 

C7 X — I- G L. 1 i i. O X. X X — ClilvJ ^vULillUC • 


v 

X 


fi^TDI l"7\ 

\AnJL) 


Uclctc Llllo Llic dllU cX 1 C i. I (Jill r 1 r. 


[N J 


InETJ 


Dave unis me ana continue. 


[N] 


gm/z) 


Save this file and exit from PIP. 


n 

V 


(RET) 


Save this file and return to command mode. 


Q 


gTRl/Z] 


Save this file and exit from PIP. 


G 


m 


Delete this and all remaining candidates, 
list deleted files, and return to PIP 
command mode. 


G 


gTRLg) 


Delete this and all remaining candidates, 
list deleted files, and exit from PIP. 



Examples 

1. PIP>MYFILE.DAT;*/SD 

DELETE FILE DB1: [200, 200]MYFILE. DAT; 1 [Y/N/G/Q] ? Y W) 
DELETE FILE DB 1: [200, 200 ]MYFILE . DAT ; 2 [Y/N/G/Q]? G © 

THE FOLLOWING FILES HAVE BEEN DELETED: 
DB1: [200, 2001MYFILE.DAT; 2 
DB1: [200, 200]MYFILE.DAT;3 
PIP> 

Deletes MYF ILE . DAT ; 1 and PIP goes to the next candidate, 
MYFILE. DAT; 2. Deletes this file and all remaining versions 
of MYFILE . DAT. Lists the deleted files and then PIP prompts 
for the next command. 

2. PIP>TEST.*; */SD 

DELETE FILE DB 1: [200, 200] TEST. DAT; 1 [Y/N/G/Q] ? N (RET) 
DELETE FILE DB1: [200, 200]TEST. TXT; 3 [Y/N/G/Q]? Q Ctrl® 

Saves TEST. DAT; 1. PIP goes on to the next candidate, 
TEST.TXT;3. Saves this file and all remaining files with 
file name TEST and then exits from PIP. 



3.2.2.23 /SP — Spool Switch - The Spool switch (/SP) directs a file 
to a line printer for printing. This switch applies only if you have 
the Print Spooler task (RSX-11M) or the Queue Manager (RSX-11M/M-PLUS* 
installed. (For more information on the Queue Manager and the Print 
Spooler, see the RSX-11M/11M-PLUS Batch and Queue Operations Manual . ) 
Specify the /SP switch in the following format: 

infilel[,infile2...,infilen]/SP[:n] 
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infile 

The file specification of the file to be spooled for printing. 
The file specification takes the form: 

dev: [ufd] f ilename.f iletype ; version 

The file specification must be issued because a null file name, 
file type, and version do not default to *.*;*. 

If the file is specified by its file identification number 
(file-ID), it will be printed. File identification numbers are 
discussed in Section 3.2.2.10. 

/SP 

The Spool switch. 



The number of copies you want spooled. (If a deleting spooler 
was specified during system generation, only one copy of a file 
is printed, regardless of the value of n. The file is deleted 
after the first copy has been printed.) If n is omitted, a value 
of 1 is assumed. 



Example 

PIP>RICK1.LST;1,KATHY.LST;1,/FI: 12: 22/SP 

Spools the files RICK1.LST;1, KATHY. LST; 1, and the file whose 
file identification number (file-ID) is 12:22 for asynchronous 
pr inting . 



3.2.2.24 /SR — Shared Reading Switch - The Shared Reading switch 
(/SR) allows you to read a file that has already been opened for 
writing by another task. You have no guarantee that you will get the 
information you want since the EOF pointer may be incorrect at the 
time you open the file. Specify the /SR switch in the following 
format : 

outf ile=inf ile/SR 

outf ile 

The output file specification, 
infile 

The input file specification. 

/SR 

The Shared Reading switch. 



Example 

PI P>TI:=[210, 20]FILES.DAT/SR 

Enables you to read FILES. DAT even though another task may have 
already opened it for writing. 
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3.2.2.25 /TD — Today Default Switch - The Today Default switch (/TD) 
restricts file searches to files created on the current day. Specify 
the /TD switch in the following format: 

/TD 

/TD 

The Today Default switch 

Note that specifying the wildcard for both startdate and enddate of 
the /DD switch (/DD:*:*) also negates /the TD switch (/DD, see Section 
3.2. 2. 4) . 

Examples 

PIP>/TD/LI 

DIRECTORY DB 2: [301 , 357 ] 
20-JAN-81 11:02 
DAY OF 20-JAN-81 

TEST. DAT; 1 1. 20-JAN-81 10:40 

FILES. TXT;1 1. 20-JAN-81 10:41 

INFO.DAT;l 1. 20-JAN-81 10:50 

TOTAL OF 3./15. BLOCKS IN 3. FILES 



3.2.2.26 /TR — Truncate Switch - The Truncate switch (/TR) allows 
you to truncate files back to their logical end-of-file point. Note 
that RMS-11 files other than those that are fixed-length, 
variable-length, or sequenced cannot be truncated. Specify /TR in the 
following format: 

infilel[,infile2...,infilen] /TR 

inf ile 

The input file specification. 

The file specification must be issued because an unspecified file 
name, file type, and version do not default to *.*;*. 

/TR 

The Truncate switch. 



Example 

PIP>*. MAC/LI 

DIRECTORY DR2: [301,7] 
2-AUG-81 15:32 

A. MAC;1 3. 20-SEP-80 14:02 

B. MAC;1 2. 20-SEP-80 15:38 

C. MAC;2 5. 28-SEP-80 09:54 

TOTAL OF 10. /15. BLOCKS IN 3. FILES 
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PIP>*.MAC/TR 
PI P>*. MAC/LI 

DIRECTORY DR2: [301,7] 
2-AUG-81 15:33 

A . MAC ; 1 3. 20-SEP-80 14:02 

B. MAC; 1 2. 20-SEP-80 15:38 

C. MAC;2 5. 28-SEP-80 09:54 

TOTAL OF 10. /10. BLOCKS IN 3. FILES 

FCS allocates a certain number of blocks to a file. The file may 
or may not use the number of blocks allocated to it. The /TR 
switch moves the EOF pointer to the end of the file and frees the 
unused blocks for use by other files. 



3.2.2.27 /UF — User File Directory Switch - The User File Directory 
switch (/UF) creates a UFD entry in the Master File Directory (MFD) on 
the volume to which you are transferring a file. You must also 
transfer ownership of the file to access the file. Use the /FO 
subswitch to transfer file ownership, and use [*,*] as the UFD in the 
output file specification if you want to create the UFD(s) from which 
you are obtaining the files being transferred. Specify the /UF switch 
in the following format: 

outf ile/UF [/FO] =inf ilel. . . , inf ilen 

outf ile 

The file specification for the output file, 
inf ile 

The file specification for the input file. 

/UF 

The User File Directory switch. 

/FO 

The File Ownership subswitch. The /FO subswitch is described in 
Section 3.2.1. 



Example 

PIP>DK6: [*,*] /UF/FO=SY: [104, 20] *.MAC, * . OB J 

To use the /UF switch, you must have write access to the Master File 
Directory of the volume on which the files are being written. If that 
volume is a system volume, you must have a system-level UIC to use the 
/UF switch. If the volume to which you are writing files is your 
private volume, use the following procedure to change your UIC so that 
you can write to it. 

1. Log onto the system under your UIC. 

2. Reset your UIC to a privileged class using the SET command: 

SET /UIC=[group, member] 

where group and member specify a privileged class. 
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A typical use of the /UF switch is creation of a backup volume. In 
the following command, you are writing all files with file types .OBJ 
and .MAC in UFD [104,20] to a backup volume called DK6: . 



3.2.2.28 /UN — Unlock Switch - The Unlock switch (/UN) unlocks 
(gives permission to open) a file that was locked because it was 
improperly closed. If a program using File Control Services (FCS) has 
a file open with write access and exits without first closing the 
file, the file is locked against further access as a warning that it 
may not contain proper information. Typically, the following 
information is not written to the file: 

1. The current block buffer being altered 

2. The record attributes that contain the end-of-file 
information 

After you have used the /UN switch, you can access the file, determine 
the extent of the damage, and, if possible, take corrective action. 
Specify the Unlock switch in the following format: 

infilel[,infile2...,infilen] /UN 

inf ile 

The file specification for the file to be unlocked. The file 
specification takes the form: 

dev : [ufd] f ilename.fi letype ; vers ion 

The file specification must be given because a null file name, 
file type, and version do not default to *.*;*. 

You must run PIP under the UIC of the file owner or under a 
system-level UIC. 

/UN 

The Unlock switch. 
Example 

PIP>DK1: [100, 100]RICKl.OBJ;3/UN 

Unlocks the file RICK1.0BJ;3 in directory [100,100] on device 
DK1: . 



3.2.2.29 /UP — Update Switch - The Update switch (/UP) is similar to 
the basic PIP copy function or the Merge switch except that an 
existing file is opened and new data is written into it from the 
beginning. Existing data in the output file is destroyed and replaced 
by the data that constitutes the input file(s). Unlike the Supersede 
switch /SU, (Section 3.2.1) /UP does not delete the existing file 
before rewriting the data. Therefore, its file identification number 
(File-ID) remains the same. Also, the number of blocks allocated to 
the output file can be the same or greater, but never less than the 
number of blocks allocated to the existing file. However, as with the 
/SU switch, the file's name, type, and version number remain the same. 
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Specify the Update switch in the format: 

outfile=infilel[,infile2... , inf ilen] /UP [/FO] 
outf ile 

The file specification for the file to be rewritten. The file 
specification takes the form: 

dev: [ufd] filename . filetype ; version 

As for the Merge and the Append switches, the output file 
specification must be explicit, that is, no wildcards are 
allowed . 

The characteristics and record attributes of the output file are 
taken from the first input file. 



inf ile 



/UP 



The file specification for the file to be copied into the file 
that is being rewritten. The input file spec i ficat ion ( s) take 
the form: 

dev: [ufd] filename . fi letype ; version 

An unspecified file name, file type, and version default to *.*;* 



The Update switch. 



/FO 

The Set File Ownership subswitch, which specifies that the owning 
UIC of the output file corresponds to the directory into which 
the file was entered. If you do not specify the /FO switch, the 
owning UIC of all new files is the UIC under which PIP is 
running, regardless of the directory into which the file was 
entered. Refer to Section 3.2.1 for examples for using the /FO 
subswitch. 

Example 

PI P>DK1 : SAMPLE . DAT ; 1=TEST1 . DAT ; 1 , TEST2 . DAT ; 1 , TEST3 . DAT ; 1/UP 

Opens SAMPLE. DAT; 1 on DK1: and replaces the data currently in 
the file with the contents of files TEST1. DAT; 1, TEST2. DAT ; 1 and 
TEST 3. DAT ; 1 . 



3.3 PIP ERROR MESSAGES 

Errors encountered by PIP during processing are displayed in the 
following format: 

PIP — <main error message> 

<filename or filespec> - <secondary error message> 
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The file name or file specification, if present, identifies the file 
or set of files being processed when the error occurred. If the error 
was detected by the operating system, file system, or device driver, 
the secondary error message is included to explain the cause of the 
error . 

PIP error messages are contained in a message file on the system 
device. If PIP cannot access the message file, errors are reported in 
the following format: 

PIP — ERROR CODE nn. 

<filename or filespec> - <driver Code -mm.> 
or 

<QIO Error Code -qq.> 

nn 

One of the PIP error codes contained in Table 3-6. 

-nm 

One of the standard system, file primitive, or FCS codes listed 
in the IAS/RSX-11 I/O Operations Reference Manual . 

-qq 

One of the directive error codes listed in IAS/RSX-11 I/O 
Operations Reference Manual . 

The PIP error messages, their descriptions and suggested user actions 
are as follows: 

PIP — ALLOCATION FAILURE - NO CONTIGUOUS SPACE 

Explanation: Not enough contiguous space was available on the 
output volume for the file being copied. 

User Action: Delete all files that are no longer required on the 
output volume, then reenter the command line. Also, use the BRU 
or DSC utilities to compress the files on your disk. BRU is 
described in Chapter 7 and DSC is described in Chapter 8. 



PIP — ALLOCATION FAILURE ON OUTPUT FILE 



or 



PIP — ALLOCATION FAILURE - NO SPACE AVAILABLE 

Explanation: Not enough space was available on the output volume 
for the file being copied. 

User Action: Delete all files that are no longer required on the 
output volume, then reenter the command line. Also, use the BRU 
or DSC utilities to compress the files on your disk. BRU is 
described in Chapter 7 and DSC is described in Chapter 8. 
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PIP — BAD USE OF WILD CARDS/CHARACTERS IN DESTINATION FILE NAME 

Explanation: A wildcard/character was specified for an output 
file name when use of a wildcard/character was explicitly 
disallowed . 

User Action: Reenter the command line with the output file 
explicitly specified. 



PIP — CANNOT EXCLUDE *.*;* 

Explanation: The /EX switch does not accept all wildcards as the 
input file specification. 

User Action: Determine the files to be excluded and reenter the 
command line. 



PIP — CANNOT FIND DIRECTORY FILE 

Explanation: The specified UFD does not 

User Action: Reenter the command line, 
UFD or the correct volume. 



PIP — CANNOT FIND FILE(S) 

Explanation: The file(s) specified in the command 
not found in the designated directory. 

User Action: Check the file specification and 
command line. 



PIP — CANNOT RENAME FROM ONE DEVICE TO ANOTHER 

Explanation: You attempted to rename a file across devices. 

User Action: Reenter the command line, renaming the file on the 
input volume, then enter another command to transfer the file to 
the intended volume. 



PIP — CANNOT TRUNCATE THIS FILETYPE 

Explanation: PIP can only truncate files containing 
fixed-length, variable-length, and sequenced records. 

User Action: Check the file specification and reenter the 
command line. 



exist on the volume, 
specifying the correct 



line was (were) 
reenter the 
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PIP — CLOSE FAILURE ON INPUT FILE 
or 

PIP — CLOSE FAILURE ON OUTPUT FILE 

Explanation: The input or output file could not be properly 
closed. If the failure is on the output file, the output file is 
then locked to indicate possible corruption. 

User Action: Reenter the command line. If the error recurs, run 
a validity check of the file structure using the Verify utility 
(VFY) on the volume in question to determine if it is corrupted. 
VFY is described in Chapter 9. 

PIP — COMMAND SYNTAX ERROR 

Explanation: Command did not conform to syntax rules. 

User Action: Reenter the command line with the correct syntax. 

PIP — DEVICE NOT MOUNTED/ALLOCATED 

Explanation: The drive had not been allocated, the device was 
not mounted, or another user had mounted the device. 

User Action: Allocate the drive and/or mount the device, then 
reenter the command line. 

PIP — DIRECTORY WRITE PROTECTED 

Explanation: PIP could not remove an entry from a directory 

because the device was wr i te-protected or because of a privilege 
violation . 

User Action: Enable the device for write operations or have the 

owner of the directory change its protection. 

PIP — ERROR FROM PARSE 

Explanation: The specified directory file does not exist. 

User Action: Reenter the command line with the correct UIC 
specified . 

PIP — EXPLICIT OUTPUT FILENAME REQUIRED 
Explanation: Self-explanatory. 

User Action: Reenter the command line with the output filename 
explicitly specified. 
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PIP — FAILED TO ATTACH OUTPUT DEVICE 
or 

PIP — FAILED TO DETACH OUTPUT DEVICE 

Explanation: An attempt to attach/detach a record-oriented 
output device failed. This is usually caused by the device being 
off-line or nonresident. 

User Action: Ensure that the device is on-line and reenter the 
command line. 



PIP — FAILED TO ATTACH TERMINAL 

Explanation: PIP could not attach a terminal, probably because 
of a privilege violation. 

User Action: Determine the cause of the failure and correct it. 
Reenter the command line. 



PIP — FAILED TO CREATE OUTPUT UFD 

Explanation: PIP could not create an entry in a directory 
because the device was wr ite-protected or because of a privilege 
violation . 

User Action: Enable the unit for write operations or have the 
owner of the directory change its protection. 



PIP — FAILED TO DELETE FILE 
or 

PIP — FAILED TO MARK FILE FOR DELETE 

Explanation: You attempted to delete a protected file. 

User Action: Request PIP under the correct UIC and reenter the 
command line. 



PIP — FAILED TO ENTER NEW FILE NAME 

Explanation: You specified a file that already exists in the 
directory file, or you did not have the necessary privileges to 
make entries in the specified directory file. 

User Action: Reenter the command line, ensuring that the file 
name and UFD are specified correctly, or request PIP under the 
correct UIC and reenter the command line. 



PIP — FAILED TO FIND FILE(S) 

Explanation: The file(s) specified in the command line was (were) 
not found in the designated directory. 

User Action: Check the file specification and reenter the 
command line. 
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PIP — FAILED TO GET TIME PARAMETERS 

Explanation: An internal system failure occurred while PIP was 
trying to obtain the current date and time. 

User Action: Reenter the command line. If the problem persists, 
submit a Software Performance Report (SPR). 



PIP — FAILED TO OPEN INDEX FILE 

Explanation: PIP was unable to read the index file, probably 
because of a privilege violation. 

User Action: Retry the operation by running PIP under a system 
UIC, or have the system manager change the protection on the 
index file. 



PIP — FAILED TO OPEN STORAGE BITMAP FILE 

Explanation: PIP could not read the specified volume's storage 
bit map, probably because of a privilege violation. 

User Action: Retry the operation by running PIP under a system 
UIC, or have the system manager change the protection on the 
storage bit map. 



PIP — FAILED TO READ ATTRIBUTES 

Explanation: The volume you specified was corrupted or you did 
not have the necessary privileges to access the file. 

User Action: Ensure that PIP is running under the correct UIC. 
If the UIC is correct, then run the validity check of the File 
Structure Verification Utility (VFY) against the volume in 
question to determine where and to what extent the volume is 
corrupted. VFY is described in Chapter 9. 



PIP — FAILED TO REMOVE DIRECTORY ENTRY 

Explanation: PIP could not remove an entry from a directory 
because the unit was wr ite-protected or because of a privilege 
violation . 

User Action: Enable the unit for write operations or have the 
owner of the directory change its protection. 



PIP — FAILED TO RESTORE ORIGINAL DIRECTORY ENTRY - FILE IS LOST 

Explanation: PIP has removed a file from a directory, failed to 
enter it (using /RE) into another directory, and failed to 
replace the original directory entry. 

User Action: Run the lost check of the File Structure 
Verification Utility (VFY) to recover the file name. VFY is 
described in Chapter 9. 
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PIP — FAILED TO SPOOL FILE FOR PRINTING 

Explanation: The Queue Manager is not installed. 

User Action: Install the Queue Manager and reenter the command 
1 ine . 



PIP — FAILED TO TRUNCATE FILE 

Explanation: The volume you specified is corrupted or you did 
not have the necessary privileges (write, extend) to truncate 
this file. 

User Action: Ensure that PIP is running under the correct UIC. 
If the UIC is correct, then run the validity check of the File 
Structure Verification Utility (VFY) against the volume in 
question to determine where and to what extent the volume is 
corrupted. VFY is described in Chapter 9. 



PIP — FAILED TO WRITE ATTRIBUTES 

Explanation: The volume you specified is corrupted or you did 
not have the necessary privileges to write the file attributes. 

User Action: Ensure that PIP is running under the correct UIC. 
If the UIC is correct, then run the validity check of the File 
Structure Verification Utility (VFY) against the volume in 
question to determine where and to what extent the volume is 
corrupted. VFY is described in Chapter 9. 



PIP — FILE IS LOST 

Explanation: PIP has removed a file from its directory, failed 
to delete it, and failed to restore the directory entry. 

User Action: Run the lost check of the File Structure 
Verification Utility (VFY) to recover the file name. VFY is 
described in Chapter 9. 



PIP — FILE NOT LOCKED 

Explanation: The /UN switch was entered for a file that was not 
locked . 

User Action: Reenter the command line, specifying the correct 
file. 



PIP — GET COMMAND LINE - BAD @ FILE NAME 

Explanation: An illegal indirect command file name was 
specified . 

User Action: Reenter the command line, specifying the correct 

name for the indirect command file. 
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PIP - GET COMMAND LINE - FAILED TO OPEN @ FILE 

Explanation: PIP could not find the specified indirect command 
file. 

User Action: Check the specification for the indirect command 
file and reenter the command line. 



PIP — GET COMMAND LINE - I/O ERROR 

Explanation: An I/O error occurred during an attempt to read a 
command line. 

User Action: Check the command to ensure that you entered it 
correctly, then reenter the command line. If the error persists, 
submit a Software Performance Report (SPR). 

PIP — GET COMMAND LINE - MAX @ FILE DEPTH EXCEEDED 

Explanation: The maximum level of nesting for indirect command 
files (4) was exceeded. 

User Action: Reduce the level of nesting. 

PIP — ILLEGAL COMMAND 

Explanation: The command was not recognized by PIP. 

User Action: Reenter the command line with the PIP command 
correctly specified. 

PIP — ILLEGAL EOF VALUE 

Explanation: You specified an illegal block and/or byte value in 
the command line. 

User Action: Reenter the command line with the correct values. 

PIP — ILLEGAL RESPONSE - TRY AGAIN, 
Explanation: Self-explanatory. 

User Action: Check which response you want and enter it when PIP 
prompts you. 

PIP — ILLEGAL SWITCH 

Explanation: The specified switch was not a legal PIP switch. 

User Action: Reenter the command line with the correct switch 
specification . 
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PIP — ILLEGAL COPY TO SAME DEVICE AND DIRECTORY 

Explanation: You attempted to copy all versions of a file into 
the same directory that is being scanned for input files. This 
would result in an infinite number of versions of the same file, 
so is not allowed. 

User Action: Reenter the command line, renaming the files or 
copying them into a different directory. 



PIP — ILLEGAL USE OF WILDCARD VERSION OR LATEST VERSION 

Explanation: The use of either a wildcard version number or a 
latest version number in the attempted operation would result in 
inconsistent or unpredictable output. 

User Action: Reenter the command line with different options or 
with an explicit or default version number. 



PIP — INPUT FILES HAVE CONFLICTING ATTRIBUTES 

Explanation: The input files specified in a Merge, Update, or 
Supersede command had conflicting attributes or the attributes of 
the input file(s) specified in an Append command conflicted with 
those of the output file. 

User Action: The message is a warning only. The specified 
action was completed despite the conflict. With a Merge, Update, 
or Supersede command, the attributes of the output file will be 
those of the first input file. With an Append command, the 
attributes of the output file are unchanged. The resulting file 
should, however, be suspect because its attributes may not 
correctly represent all the records in the file. 



PIP — I/O ERROR ON INPUT FILE 
or 

PIP — I/O ERROR ON OUTPUT FILE 

Explanation: One of the following conditions may exist: 



• 


The 


device is not on-line 


• 


The 


device is not mounted 


• 


The 


hardware has failed 


• 


The 


volume is full (output only) 


• 


The 


input file is corrupted 



Note that these are the most common conditions. Conditions other 
than those listed may have caused the message. 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 
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PIP — NOT A DIRECTORY DEVICE 

Explanation: A directory-oriented command was issued to a device 
that does not have directories (such as a printer). 

User Action: Reenter the command line without specifying a UFD. 



PIP — NOT ENOUGH BUFFER SPACE AVAILABLE 

Explanation: PIP did not have enough I/O buffer space to perform 
the requested command. 

User Action: Have the system manager install PIP in a larger 
partition or increase the size specified by the /INC switch with 
the MCR INSTALL command. See the RSX-11M/M-PLUS MCR Operations 
Manual . 



PIP ~ NO SUCH FILE (S ) 

Explanation: The file(s) specified in the command was (were) not 
found in the designated directory. 

User Action: Check the file specification and reenter the 
command line. 



PIP — ONLY [*,*] IS LEGAL AS DESTINATION UIC 

Explanation: A UFD other than [*,*] was specified as the output 
file UFD for a copy operation. 

User Action: Reenter the command line with [*,*] specified as 
the output UFD. 



PIP — OPEN FAILURE ON INPUT FILE 
or 

PIP — OPEN FAILURE ON OUTPUT FILE 

Explanation: The specified file could not be opened. One of the 
following conditions may exist: 

• The file is protected against access. 

• A problem on the physical device (for example, device down) . 

• The volume is not mounted. 

• The specified file directory does not exist. 

• The named file does not exist in the specified directory. 

Note that these are the most common conditions. Conditions other 
than those listed may have caused the message. 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 
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PIP — OUTPUT FILE ALREADY EXISTS — NOT SUPERSEDED 

Explanation: An output file of the same name, type, and version 
as the file specified already exists. 

User Action: Retry the copy with /NV to assign a new version 
number or use /SU to supersede the output file. 



PIP — TOO MANY COMMAND SWITCHES - AMBIGUOUS 

Explanation: Too many switches were specified or the switches 
confl ict . 

User Action: Reenter the command line, specifying the correct 
set of switches. 



PIP — VERSION MUST BE EXPLICIT OR " * " 

Explanation: The version number of the specified file must be 
expressed explicitly or as a wildcard (*). 

User Action: Reenter the command line with the version number 
correctly expressed. 



3.4 PIP ERROR CODES 

Table 3-6 identifies the error codes PIP issues when it does not have 
access to the message file. The descriptions and suggested user 
actions for these error codes are identical to those described in 
Section 3.3. 
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Table 3-6 
PIP Error Codes 



Error Code 


Error Message 


1 


COMMAND SYNTAX ERROR 


2 


ILLEGAL SWITCH 


3 


TOO MANY COMMAND SWITCHES - AMBIGUOUS 


4 


ONLY [*,*] IS LEGAL AS DESTINATION UIC 


5 


ILLEGAL COMMAND 


6 


ILLEGAL "*" COPY TO SAME DEVICE AND DIRECTORY 


7 


BAD USE OF WILDCARDS/CHARACTERS IN DESTINATION FILE NAME 


8 


EXPLICIT OUTPUT FILE NAME REQUIRED 


9 


ALLOCATION FAILURE - NO CONTIGUOUS SPACE 


10 


ALLOCATION FAILURE - NO SPACE AVAILABLE 


11 


ALLOCATION FAILURE ON OUTPUT FILE 


12 


I/O ERROR ON INPUT FILE 


13 


I/O ERROR ON OUTPUT FILE 


14 


ILLEGAL USE OF WILDCARD VERSION OR LATEST VERSION 


15 


FAILED TO CREATE OUTPUT UFD 


16 


INPUT FILES HAVE CONFLICTING ATTRIBUTES 


17 


OPEN FAILURE ON INPUT FILE 


18 


OPEN FAILURE ON OUTPUT FILE 


19 


CLOSE FAILURE ON INPUT FILE 


20 


CLOSE FAILURE ON OUTPUT FILE 


21 


FAILED TO DETACH OUTPUT DEVICE 


22 


DEVICE NOT MOUNTED/ALLOCATED 


23 


OUTPUT FILE ALREADY EXISTS - NOT SUPERSEDED 


24 


FAILED TO MARK FILE FOR DELETE 


25 


FILE IS LOST 


26 


VERSION MUST BE EXPLICIT OR "*" 


27 


ERROR FROM PARSE 


28 


FAILED TO DELETE FILE 


29 


FAILED TO ATTACH TERMINAL 


30 


ILLEGAL RESPONSE - TRY AGAIN 


31 


CANNOT EXCLUDE *.*;* 


32 


CANNOT FIND DIRECTORY FILE 


33 


FAILED TO ATTACH OUTPUT DEVICE 


34 


FAILED TO GET TIME PARAMETERS 


35 


NOT A DIRECTORY DEVICE 


36 


FAILED TO WRITE ATTRIBUTES 


37 


FAILED TO READ ATTRIBUTES 


38 


FILE NOT LOCKED 


39 


FAILED TO ENTER NEW FILE NAME 


40 


FAILED TO RESTORE ORIGINAL DIRECTORY ENTRY - FILE IS LOST 


41 


CANNOT RENAME FROM ONE DEVICE TO ANOTHER 


42 


FAILED TO SPOOL FILE FOR PRINTING 


43 


CANNOT SPOOL BY FILE ID (RSX-11D only) 


44 


FAILED TO OPEN STORAGE BITMAP FILE 


45 


FAILED TO OPEN INDEX FILE 


46 


FAILED TO FIND FILE(S) 


47 


CANNOT FIND FILE (S) 


A ft 


NO «5 MP H FTTEWCM 
is kj o uv^ n r x l>Ej \ o ) 


49 


FAILED TO REMOVE DIRECTORY ENTRY 


50 


DIRECTORY WRITE PROTECTED 


51 


NOT ENOUGH BUFFER SPACE AVAILABLE 


52 


FAILED TO TRUNCATE FILE 


53 


CANNOT TRUNCATE THIS FILETYPE 


54 


ILLEGAL EOF VALUE 
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FILE TRANSFER PROGRAM (FLX) 



The File Transfer Utility Program (FLX) allows you to use foreign 
volumes (not in Files-11 format) in DIGITAL'S DOS-11 or RT-11 format. 
FLX converts the format of a file to the format of the volume the file 
is being transferred to. 

FLX can be used to initialize and list directories of cassettes and 
RT-11 or DOS-11 file-structured volumes. FLX can also be used to 
delete files from RT-11 or DOS-11 formatted volumes. 

FLX performs file transfers (and format conversions, as appropriate) 
from : 

• DOS-11 to Files-11 volumes 

• Files-11 to DOS-11 volumes 

• DOS-11 to DOS-11 volumes 

• Files-11 to Files-11 volumes 

• Files-11 to RT-11 volumes 

• RT-11 to RT-11 volumes 

• RT-11 to Files-11 volumes 
Valid DOS-11 devices are: 



Device 



Device Abbreviation 



PC 11 paper tape punch 

PC11 or PR11 paper tape reader 

RK05 cartridge disk 

TU78 magnetic tape 

TE16, TU16, TU45, or TU77 magnetic tape 

TS04 magnetic tape 

TU10, or TS03 magnetic tape 

TU56 DECtape 

TU60 tape cassette 



PP 
PR 
DK 
MF 
MM 
MS 
MT 
DT 
CT 
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Valid RT-11 devices are: 



Device 



Device Abbreviation 



RL01/RL02 cartridge 

RK05 cartridge disk 

RK06 or RK07 cartridge disk 

RX01 floppy disk 

RX02 floppy disk 

TU56 DECtape 

TU58 DECtape II data cartridge 



DL 
DK 
DM 
DX 
DY 
DT 
DD 



FLX supports all Files-11 devices, including RSX-format cassettes. 
They are volumes that you have initialized using the MCR INITVOL or 
DC L INITIALIZE command. DOS-11 and RT-11 volumes are initialized 
using FLX. On RSX-11M-PLUS, DOS-11 and RT-11 volumes must be mounted 
with foreign characteristics before you can use FLX. On RSX-11M, such 
volumes must be unmounted. 

You can use FLX interactively or by means of an indirect commmand 
file. FLX allows only one level of indirect command file 
speci f icat ion . 

You can invoke FLX in two ways: by specifying FLX or by specifying 
FLX and a command line. If you only specify FLX, the utility responds 
with the prompt: 



FLX can also access an indirect command file in the following manner: 
>FLX @FOO.CMD 
or 

FLX>@FOO.CMD 
4.1 FLX COMMAND FORMAT 

Although formats for specifying FLX functions vary, the general format 
for entering FLX command lines is: 

devicespec/sw=inf ile/sw, . . . , inf ilen/sw 

devicespec 

The device specification for the FLX output device, which takes 
the form: 

dev : [uf d] 

The [ufd] field is optional; if it is not specified, FLX uses 
the current UIC. Do not specify a UFD if the output device is in 
RT-11 format. 



FLX> 
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If you explicitly enter the output device specification, you must 
enter the equal sign. 

FLX does not permit output file specifications. The output files 
take the names of the input files. 

inf ilen 

The input file specifications, which take the form: 

dev: [ufd] f ilename.f iletype ;version 
The UFD is not specified for RT-11 volumes. 

/sw 

One of three types of FLX switches described below in Section 
4. 2. 

FLX supports 9-character file names for DOS-ll-format magnetic tapes. 
When you transfer the file back to Files-11 format, (which uses a 
12-character filename) FLX will recover the last three characters. 

Wildcards are valid only for input file specifications. 

Version numbers are valid only for Files-11 files and cannot be 
specified as wildcards. The standard rules for updating version 
numbers apply (see the RSX-11M/M-PLUS MCR Operations Manual ) . 



4. 2 FLX SWITCHES 

FLX provides three types of switches for file transfers: 

• Volume format switches 

• Transfer mode switches 

• Control switches 



Volume format switches specify the format of the volume on which files 
are stored; that is, Files-11, DOS-11, or RT-11 volumes. 

Transfer mode switches provide the means for specifying the format of 
a file on a non-Files-11 volume. Files can be in formatted ASCII, 
formatted binary, or file image format. 

Control switches provide control functions useful during file 
transfers. Using file control switches, you can specify, for example, 
the number of blocks to be allocated to an output file or the UFD for 
an output file. 
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4.2.1 Volume Format Switches 

FLX has three volume format switches that define the format of the 
specified volumes. 

/DO Identifies the volume as a DOS-11 formatted volume. 

/RS Identifies the volume as a Files-11 formatted volume. 

/RT Identifies the volume as an RT-11 formatted volume. 

Initially, input volumes default to DOS-11 format and output volumes 
default to Files-11 format. FLX assumes these default volume formats 
if you do not specify switches in the command line. 

You can change the initial default by entering /RS or /DO on a command 
line by itself. /RS sets the default for input volumes to Files-11 
format and output volumes to DOS-11 format. /DO sets the default for 
input volumes to DOS-11 format and output volumes to Files-11 format. 

For example, to specify the default transfer direction from Files-11 
to DOS-11, type: 

FLX>/RS 

To specify the default transfer direction from DOS-11 to Files-11, 
type: 

FLX>/DO 

If /RT is specified on one side of a command line, the default entry 
for the other side is /RS. 

Examples 

1. FLX>DK0: =DT0: SYS1.MAC/RT 

The output is defaulted to /RS. 

2. FLX>DK0:/RT=DK0:SYS1.MAC 

The input is defaulted to /RS. 



4.2.2 Transfer Mode Switches 

FLX has three transfer mode switches, one for each type of file 
format. Files can be in formatted ASCII, formatted binary, or file 
image format. Format conversions can be in either direction, and are 
between DOS-11 files and Files-11 files or between RT-11 files and 
Files-11 files. Specifying a transfer mode switch determines which 
format the output file will be in after the conversion of the file. 
Table 4-1 describes the transfer mode switches. 
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Table 4-1 
FLX Transfer Mode Switches 



Switch Description 



/FA: n Formatted ASCII 

The DOS-11 or RT-11 output file is to be formatted ASCII. 
Formatted ASCII is defined as ASCII data records 
terminated by a carriage return/line feed (RET-LF) , form 
feed (FF) , or vertical tab (VT) . In transfers from 
DOS-11 or RT-11 files to Files-11 files, RET-LF pairs are 
removed from the end of records. In transfers from 
Files-11 files to DOS-11 or RT-11 files, RET-LF pairs are 
added to the end of each record that does not already end 
with LF or FF. In both directions, all nulls, rubouts, 
and vertical tabs are removed from input records. 

If you specify /FA:n with Files-11 output, fixed-length 
records of size n are generated. Output records are 
padded with nulls, if necessary. 

If you do not specify /FA:n with Files-11 output, FLX 
generates variable-length records. The output record 
size equals the input record size. 

ASCII data is transferred as 7-bit values. Bit 8 of each 
byte is masked off before transfer. CTRL/Z (ASCII 032 
octal) is treated as the logical end-of-input file for 
formatted ASCII transfers from DOS-11 cassette or paper 
tape to Files-11. 

/FB:n Formatted Binary 

The DOS-11 or RT-11 output file is to be formatted 
binary. In this mode, formatted binary headers and 
checksums are added to records that are output to DOS-11 
or RT-11 files, and removed when transferred to Files-11 
files . 

If you specify /FB:n with Files-11 output, fixed-length 
records of size /FB:n are output (512 (10) bytes is the 
maximum) . FLX pads records with nulls to create the 
specified length. 

If you do not specify /FB:n with Files-11 output, FLX 
generates variable-length records. The output record 
size equals the input record size. 

/IM:n Image Mode 

The transfer is to be in image mode. Image mode forces 
fixed-length records. You can use the value n to 
indicate the desired record length (in decimal bytes) for 
Files-11 output (512 (10) bytes maximum) . If you do not 
specify n, FLX assumes a record length of 512(10) bytes. 
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FLX assumes the following default transfer modes for these file types 
(with the exception of paper tape transfers described in Section 4.6). 

Mode Switch File Type 

Image /IM:n . TSK, . OLB , .MLB, .SYS, 

.SML, . ULB , .EXE 

Formatted Binary /FB:n .OBJ, .STB, .BIN, . LDA 

Formatted ASCII /FA : n All others 

If you specify n with /FA, /FB, or /IM when the output file is not a 
Files-11 file, FLX ignores n. 

The RSX-11M/M-PLUS MCR Operations Manual defines the above file types. 



4.2.3 Control Switches 

FLX provides a number of control switches to control file processing. 
Table 4-2 describes these switches. 



Table 4-2 
FLX Control Switches 



Switch Description 



/BL:n[.] Indicates the number of contiguous blocks (n) in octal or 
decimal to be allocated to the output file. 

This switch is normally used with the /CO switch 
(described later in the table) . Because all RT-11 files 
are contiguous, the /CO switch is not required with the 
/BL:n switch for RT-11 output. 

If you do not specify /BL, the input file size is used as 
the output file size. 

The file allocation scheme used for RT-11 volumes 
normally allocates the largest available space on the 
volume for a new file. Using /BL:n with the /RT switch 
for the output file causes the output file to be 
allocated the first unused space of size n. However, 
when the RT-11 file is closed, the input file size is 
used as the output file size. If the input file is not 
n, an error results. 

/BS:n Specifies the block size n. in bytes for cassette tape 

output . 

If you do not specify /BS, a block size of 128(10) is 
assumed. /BS is only valid in a cassette tape (CT) 
output file specification with /RS specified. 

/CO Indicates that the output file is to be contiguous. The 

/CO switch is used only with disks and DECtapes. 

If the input file is on paper tape, cassette, or DOS-11 
magnetic tape, /BL is also required. FLX transfers the 



(continued on next page) 
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Table 4-2 (Cont.) 
FLX Control Switches 



Switch 



Description 



/CO 

(Cont.) 



/DE 



/DI 



file types . TSK, .SYS, and . OLB to Files-11 volumes with 
/CO implied when the input is a Files-11 volume, or a 
DOS-11 or RT-11 DECtape or disk. 

Deletes files from a DOS-11 DECtape or disk. It is used 
also with /RT to delete files from an RT-11 DECtape or 
disk. When you specify /DE, the FLX command line has no 
output specification. 

Causes a directory listing of cassettes or DOS volumes to 
be listed on a specified output file. It is used also 
with /RT to generate a directory listing of RT-11 volumes 
in a specified output file. 

You cannot list Files-11 volume directories using FLX. 

If you do not specify an output device, the directory is 

sent to TI:. If you do not specify file name and file 

type on the input file specification, a wildcard is 
assumed . 



See Section 4.3 for information on DOS-ll-volume 
directory manipulation. See Section 4.4 for information 
on RT-ll-volume directory manipulation. 

/DNStn Specifies the density of the magnetic tape; where n is 

800, 1600 or 6250 bpi. If n is any other value or not 
specified, FLX prints an error message. If you do not 
specify /DNS : n , the magnetic tape density defaults to 
6250 bpi for the TU78, 1600 bpi for the TS04, and 800 bpi 
for all other Magtape devices. If you specify /DNS with 
a nonmagnetic device, FLX ignores the switch. 

/FC When using FORTRAN files, indicates that FORTRAN carriage 

control conventions are to be used. The /FC switch 
applies only to Files-11 output files. (If you have the 
PDP-11 FORTRAN Language Reference Manual, refer to it for 
more information on FORTRAN carriage control conventions. 
Otherwise, refer to the IAS/RSX-11 I/O Operations 
Reference Manual for a discussion of the file data block 
and record attributes, of which setting carriage control 
is a part.) 

/ID Requests the current version number of FLX to be printed. 

You can specify /ID as part of an output or input 
specification or type it in response to the FLX prompt 
(FLX>) . 

/LI Same as /DI. 

/NU:n[.] Used with the /ZE and /RT switches to specify the number 
of directory blocks (n) in octal or decimal to allocate 
when initializing an RT-11 disk or DECtape. If you do 
not specify /NU:n, four directory blocks are allocated. 
The maximum number of blocks that can be allocated is 
37(8) 31 (10). 



(continued on next page) 
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Table 4-2 (Cont.) 
FLX Control Switches 



Switch 



Description 



/RW 



/SP 



/UI 



/VE 



/ZE[:n. ] 



Rewinds the magnetic tape before beginning the file 
transfer. Specifying /-RW causes FLX to begin the 
transfer without first rewinding the magnetic tape. If 
you do not specify either rewind option, the switch 
defaults to /RW. If you specify the /RW switch with a 
non-magnetic-tape device, or with /LI, /DI, or /ZE, FLX 
ignores /RW. 

Indicates that the converted file is to be spooled by the 
print spooler task or the queue management system. The 
/SP switch applies only to Files-11 output files. 

Indicates that the output file is to have the same UFD as 
the input file. FLX ignores the /UI switch if the output 
specification contains an explicit UFD. /UI is valid 
only for output files in DOS-11 or Files-11 format. 

Causes each record written to a cassette to be read and 
verified. The /VE switch is only valid with a CT output 
file specification. 

Initializes cassettes or DOS-11 volumes. It is also used 
with /RT (and /NU) to initialize RT-11 volumes. 
Initializing erases any files already on the device. The 
/ZE switch does not require a file specification. 



For DOS-11 DECtape, /ZE creates an entry for the 
UIC. 



current 



4.3 DOS-11 VOLUME DIRECTORY MANIPULATION 

This section contains examples that show how to display DOS-11 
directory listings, delete DOS-11 files, and initialize DOS-11 volumes 
using the FLX switches. 

On RSX-11M-PLUS, DOS-11 volumes must be mounted with foreign 
characteristics before you can use FLX. On RSX-11M, the volumes must 
be unmounted. 



4.3.1 Displaying DOS-11 Directory Listings 

The /LI or the /DI switch instructs FLX to send the directory of the 

cassette or DOS-11 volume specified in the input specification to the 

Files-11 file specified in the output specification. If you do not 

enter an output specification, FLX sends the directory to TI:. For 
example : 

FLX>DT0: [100, 100] *. MAC/LI 

This command line lists on your terminal the directory of all .MAC 
files under UFD [100,100] on the DOS-11 DECtape on DT0: . 

Figure 4-1 shows sample directory listings for a DOS-11 DECtape and a 
TU60 cassette. 
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DECtape Directory Listing 




O DIRECTORY 
O 19-SEP-78 


e 


DT: [200,200] O 




O FLX.TSK 
UFD.TSK 
TKN.TSK 
MOU.TSK 




©104. ©19-SEP-78 

8. 19-SEP-78 
6. 19-SEP-78 
14. 19-SEP-78 


<233> 
<233> 
<233> 
<233> 


O TOTAL OF 


132. 


BLOCKS IN 4. FILES 




Cassette Directory 


Listing 




© DIRECTORY 
O 19-SEP-78 


e 


CT: [200,200] O 




O UFD.TSK-0 
TKN.TSK-0 
MOU.TSK-0 




©28. 019 

20. 19 
52. 19 


-SEP-78 128.0 
-SEP-78 128. 
-SEP-78 128. 


O TOTAL OF 


100. 


BLOCKS IN 3. FILES 





ZK-1 80-81 

Figure 4-1 DOS-11 Directory Listings 



Notes on Figure 4-1: 

This line identifies the listing as a directory listing. 

The device name and unit number. 

The User File Directory. 

The date the directory was listed. 

The file name, file type, version number, and sequence number 
(cassettes only) . 

The file size in decimal blocks. 

The file creation date. 

The record size in decimal bytes for the file (cassettes 
only. ) 

A total of the actual file sizes and the total number of 
files in the directory. 

The default protection code provided by the system. 
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4.3.2 Deleting DOS-11 Files 

You can delete files from DOS-11 disks or DECtapes using the Delete 
switch (/DE). The /DE switch requires only the file specification for 
the file you are deleting. For example: 

FLX>DK1: [100, 100] SYS1.MAC/DE 

This command line deletes SYS1.MAC under UFD [100,100] from the DOS-11 
disk on DK1 : . 



4.3.3 Initializing DOS-11 Volumes 

You can initialize cassettes and DOS-11 volumes using the /ZE switch. 
This switch requires only the device specification for the volume you 
are initializing. For example: 

FLX>DT1:/ZE 

This command line initializes the DECtape on DTI: in DOS-11 format. 



4.4 RT-11 VOLUME DIRECTORY MANIPULATION 

You can display RT-11 directory listings, delete RT-11 files, and 
initialize RT-11 volumes using the FLX switches described in this 
section . 

On RSX-11M-PLUS , RT-11 volumes must be mounted with foreign 
characteristics before you can use FLX. On RSX-11M, the volumes must 
be unmounted. 



4.4.1 Displaying RT-11 Directory Listings 

The /LI or the /DI switch, when combined with the /RT switch, 
instructs FLX to send the directory of the RT-11 volume in the input 
specification to the Files-11 file in the output specification. If 
you do not enter an output specification, FLX sends the directory to 
TI : . For example : 

FLX>DT0: * .MAC/LI/RT 

This command lists on your terminal all .MAC files on the RT-11 volume 
on DT0: . 

Figure 4-2 shows a sample directory listing for an RT-11 disk. 
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© DIRECTORY ©DK: 
© 4-JUN-78 

OSIPBOO.MAC©49. ©4-JUN-78 
< UNUSED > 6. 

SIP .MAC 10. 4-JUN-78 

SI PCD .MAC 7. 4-JUN-78 

< UNUSED > 21. 
SIPQIO.MAC 7. 4-JUN-78 

< UNUSED > 4686. 

© 4713. FREE BLOCKS 

© TOTAL OF 73. BLOCKS IN 4. FILES 



ZK-181-81 



Figure 4-2 RT-11 RK05 Cartridge Disk Directory Listing 

Notes on Figure 4-2: 

© This line identifies the listing as a directory listing. 

© The device name and unit number. 

Q The date the directory was listed. 

© The file name and file type; <UNUSED> indicates free space. 

© The number of blocks in the file or free space. 

© The file creation date, or blank for free space. 

The total number of free blocks on the volume. 

© The total number of blocks allocated to files on the volume. 
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4.4.2 Deleting RT-11 Files 

You can delete files from RT-11 disks or DECtapes using the Delete 
switch (/DE) with the RT-11 switch (/RT) . The command line on which 
you specify /DE/RT requires only the file specification for the file 
you are deleting. For example: 

FLX>DK1:SYS/.MAC/DE/RT 

This command line deletes SYS/. MAC from the RT-11 volume on DK1 : . 



4.4.3 Initializing RT-11 Volumes 

You can initialize RT-11 volumes using the /ZE switch with the /RT 
switch. The /ZE switch requires only the device specification for the 
volume you are initializing. For example: 

FLX>DT1:/ZE/RT 

This command line initializes the DECtape on DTI: in RT-11 format. 
When you initialize RT-11 volumes, the /ZE switch takes an optional 
argument in the form: 

/ZE:n 

The value n specifies the number of extra words per directory entry. 
A directory segment consists of two disk blocks with a total of 
512(10) words. The directory header uses five words, leaving 507(10) 
words for directory entries. 

Normally, each directory entry uses seven words; two directory 
entries within each directory segment are allocated to the file 
system. Therefore, the number of entries in each segment (when no 
extra words are specified) is determined as follows: 

Directory entries = (507/7)-2 

= 72-2 
= 70 

Some RT-11 applications require extra words in the directory entries. 
When you specify extra words for directory entries (/ZE:n) , the number 
of directory entries is determined as follows: 

Directory entries = [507/ (n+7 ) ] -2 

For example, 61(10) entries can be made per directory segment if you 
specify /ZE: 1. 

Use of the /NU switch with the /ZE and /RT switches specifies the 
number of directory segments to allocate to the RT-11 volume. The /NU 
switch has the following form: 

/NU:n 
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The value n specifies the number of directory segments to allocate. 
Four directory segments are allocated by default. The maximum number 
of segments that can be allocated is 37(8) or 31(10). For example: 

FLX>DT0:/ZE: 2/NU: 6/RT 

This command line initializes the DECtape on DTO: in RT-11 format, 
allocates two extra words per directory entry, and allocates six 
directory segments. This results in a total of 54(10) directory 
entries, each of which uses 9 words. 



4.5 FLX TA11/TU60 CASSETTE SUPPORT 

FLX supports the DIGITAL standard cassette file structure. Files can 
be transferred to and from cassettes in either Files-11 format (/RS) 
or DOS-11 format (/DO). The transfer mode selected depends on the 
file format requirements. 

The file formats for Files-11 or DOS-11 cassette files are almost the 
same; that is, they both conform to the DIGITAL standard cassette 
file format. The differences between the Files-11 and DOS-11 cassette 
file formats are shown in Table 4-3. 



Table 4-3 

Differences Between Files-11 and DOS-11 Cassette Files Format 



Files-11 Format 


DOS-11 Format 


Standard level 2 

12-character file name (9- 
character file name and 3- 
character file type) 

Blocks of any size up to 
512(10) bytes (128 decimal 
bytes default) 

Version numbers 


Standard level 

9-character file name (6- 
character file name and 3- 
character file type) 

128(10)-byte blocks 
No version numbers 



Files-11 cassette file format (level 2) is a superset of the DOS-11 
cassette file format (level 0). Therefore, any cassette written in 
DOS-11 format can be read in Files-11 format. The reverse of this, 
however, is true only when: 

• The Files-11 file is written with 128(10)-byte blocks. 

• The extra file header data (such as version number) , which 
does not appear in DOS-11 files, can be ignored. 

Files-11 files and DOS-11 files can be mixed on a given cassette as 
long as you use a proper retrieval mode when you access the file. 
Files of various block sizes can also share a given cassette. FLX 
uses the block size contained in the file label data when reading a 
file. 
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4.5.1 Multivolume Cassette Support 

FLX supports multivolume cassette files in both Files-11 and DOS-11 
formats. No special switches are required to notify FLX that a 
multivolume file is being accessed. 



4.5.2 FLX Cassette Output Files 

When FLX detects the physical end-of-tape for an output cassette, the 
following sequence of events occurs. 

1. FLX issues the following message: 

FLX — END OF VOLUME ON CASSETTE 
CTn: [g,m] 

The variables n, g, and m specify the unit number, group 
number, and member number. 

2. The cassette is rewound. 

3. FLX issues an additional message: 

MOUNT NEW CASSETTE? (Y, Z (OUTPUT ONLY) OR CR) 
FLX> 

4. At this point, you have three alternatives: 

a. Mount the next output cassette volume and type Y, 
followed by a carriage return. If you select this 
alternative, the new output cassette is rewound, FLX 
searches for the logical end-of-tape (end of the last 
file) , and then continues transferring data onto the 
tape. If FLX, while searching for logical end-of-tape, 
encounters a file with the same file name as the current 
input file, it displays the following message: 

FLX -- FILE ALREADY EXISTS 

FLX then returns to step 3. 

b. Mount the next output cassette volume and type Z, 
followed by a carriage return. The new output cassette 
is rewound, and FLX continues by transferring data onto 
it. Thus, the tape is effectively zeroed (initialized) 
before data is transferred to it. 

c. Enter a carriage return to terminate the transfer. 

If you select this alternative, FLX assumes that 
end-of-file (EOF) is desired and issues the following 
message : 

FLX — REQUEST TERMINATED — LAST BLOCK NOT WRITTEN 

This message indicates that the last input file block 
processed was not written onto the tape. 
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4.5.3 FLX Cassette Input Files 

When FLX detects the physical end-of-tape for an input cassette, the 
following sequence of events occurs: 

1. FLX issues the following message, including the input file 
specification on which the end-of-tape was detected: 

FLX — END OF VOLUME ON CASSETTE 
CTn : [g ,ra] f ilename . type 

The variables n, g, and m specify the unit number, group 
number, and member number. 

2. The cassette is rewound. 

3. FLX issues an additional message: 

MOUNT NEW CASSETTE: (Y, Z (OUTPUT ONLY) OR CR) 
FLX> 

4. At this point you have two alternatives: 

a. Mount the next input cassette volume and type Y, followed 
by a carriage return to continue. If you select this 
alternative, the new input cassette is rewound, and a 
validity check is performed on the file label and 
sequence number. If the file label and sequence number 
are correct, FLX begins processing data from the volume. 
If, however, the file label and sequence number are not 
correct, FLX issues the following message: 

FLX — FILE NOT FOUND 

The process then returns to step 3. 

b. Type a carriage return to terminate the transfer. If you 
select this alternative, FLX assumes that end-of-file 
(EOF) is desired, and the transfer is terminated. If the 
input file is being processed as a formatted binary or an 
ASCII file, a format error may occur. 

If you enter Z, FLX prints the message: 

FLX — BAD RESPONSE 

The process then returns to step 3. 



4.6 FLX PAPER TAPE SUPPORT 

FLX supports the DIGITAL standard paper tape devices, such as the 
PC-11 Paper Tape Reader/Punch and the PR-11 Paper Tape Reader, as 
DOS-11 devices. 

FLX lets you delimit records on paper tape for files in formatted 
binary mode or in formatted ASCII mode. Formatted binary records are 
delimited by standard DOS-11 4-byte headers and a trailing checksum. 
Formatted ASCII records that do not already end with line feeds or 
form feeds are delimited by carriage return-line feed pairs. 
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FLX gives special treatment to files that normally default to image 
mode transfers, that is; . TSK, . OLB , .MLB, .SYS, . SML, .EXE, and . ULB 
files. On output to paper tape, these files are written, by default, 
in formatted binary. When read back from paper tape to a Files-11 
volume, the file is written by default, with fixed-length, 
512(10)-byte records. 

These defaults ensure that when the files are read back from paper 
tape they are in the same format as they were before being punched. 
However, the new files are not contiguous unless you specify /CO/BL:n 
with the output file specification. You must know an appropriate 
value for n (the number of contiguous blocks to allocate) before 
issuing the command. You can also use PIP to create a contiguous file 
from the file that is read back from tape (see Chapter 3). 

The use of explicit transfer mode switches to transfer .TSK, .OLB, 
.MLB, .SYS, .SML, .EXE, and . ULB files between paper tape and Files-11 
volumes can cause files read back from paper tape to be different from 
the files that were originally written out. 

For FLX paper tape transfer commands, you cannot specify file names in 
the output specification. The file name entered for the input file 
specification is used as the file name for the output file. For 
example : 

F LX>D K 1 : / RS =PR : CRTMAC . DAT/DO 

This command line writes an output file whose file name is 
DK1 : CRTMAC . DAT . 

If you do not specify a file name on the input file specification, the 
default file name is . ;n where n represents the latest version number. 

RSX-11M and RSX-11M-PLUS systems support paper tapes only as DOS-11 
devices. Therefore, you must specify the /DO switch with paper tape 
file specifications. The following examples show paper tape 
specifications for input and output file specifications: 

FLX>PP:/DO-CRTMAC.DAT/RS 

F LX>D K: /RS =PR : CRTMAC . DAT/DO 

To copy from one paper tape to another, use the Image-Mode switch 
(/IM) regardless of the format of the paper tapes. For example: 

FLX>PP:/DO/IM=PR:/DO 



4.7 FORTRAN DIRECT ACCESS FILES 

FORTRAN direct access files must be transferred in Image mode. For 
example : 

FLX>DK0:/DO/IM=FOO.TJP/RS 

To recover the file, you must specify the record length in bytes (not 
to exceed 512(10) bytes). For example: 

FLX>/RS/IM:n=DK0:FOO.TJP/DO 

The variable n specifies the record length in bytes. 
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4.8 FLX ERROR MESSAGES 

Errors encountered by FLX during processing are reported on the 
initiating terminal. The FLX error messages, their explanations, and 
suggested user actions are described in this section. 

FLX — EJAD LIST FILE SPEC 

Explanation: One of the following was specified: 

1. More than one output file for an /LI or /DI operation. 

2. Wildcards in the output file specification for an /LI or /DI 
operation . 

User Action: Reenter the command line correctly. 

FLX — BAD RESPONSE 

Explanation: Z was entered in response to the message: 

MOUNT NEW CASSETTE (Y, Z (OUTPUT ONLY) OR CR) 
FLX> 

The cassette in question is an input volume. 

User Action: Respond with Y or CR after the message is 
red isplayed . 

FLX — CAN'T OPEN @ FILE 

Explanation: The specified indirect command file could not be 
opened for one of the following reasons: 

• The file is protected against access. 

• A problem exists on the physical device (for example, the disk 
is not spinning) . 

• The volume is not mounted or is allocated to another user. 

• The volume is not on-line. 

• The specified file directory does not exist. 

• The named file does not exist in the specified directory. 
User Action: Correct the condition and reenter the command line. 

FLX — CO FILES TO OUTPUT DEVICE NOT ALLOWED 

Explanation: An illegal output device (for example, magnetic 
tape) was entered with the /CO switch. 

User Action: Reenter the command line without specifying the /CO 
switch. 
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FLX — CASSETTE ERROR I/O TERMINATED 

Explanation: A hardware error occurred during the end-of-volume 
sequence on a cassette volume. The transfer was aborted. 

User Action: Reenter the command line using a new cassette. 

FLX — COMMAND SYNTAX ERROR 

Explanation: The command was entered in a format that does not 
conform to syntax rules. 

User Action: Reenter the command line with the correct syntax. 

FLX — CONFLICTING TRANSFER MODES SPECIFIED 

Explanation: Conflicting transfer mode qualifiers were entered. 
For example: 

SYO: =DT0:FOO.OBJ/IM/FB 

User Action: Reenter the command line with only one transfer 
mode switch specified. 

FLX — DOS-11 OR RT-11 DEVICE NOT VALID FORMAT 

Explanation: The device specified with the /DO switch has an 
incorrect DOS-11 file structure, or the device specified with the 
/RT switch has an incorrect RT-11 file structure. 

User Action: Correctly identify the file structure on each 
volume, and then reenter the command line. 

FLX — DT: UFD FULL 

Explanation: The DECtape directory is full. 

User Action: Delete all unnecessary files, and reenter the 
command line. 



FLX — END OF VOLUME ON CASSETTE 

MOUNT NEW CASSETTE? (Y, Z (OUTPUT ONLY) OR CR) 

Explanation: Physical end-of-tape was encountered during a 
cassette transfer. The tape is rewound and you are asked to 
mount the next cassette. 

User Action: See Section 4.5.2 if an output transfer is being 
performed or Section 4.5.3 if an input transfer is being 
performed . 
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FLX — ERROR DURING DIRECTORY I/O 

Explanation: One of the following conditions may exist: 

1. The volume is not wr ite-enabled . 

2. The /DO, /RT or /RS switches were incorrectly specified. 

3. The volume is not in the proper format. 

4. A hardware error occurred during a directory I/O operation 
(for example, bad tape) . 

User Action: The following responses correspond (by number) to 
the conditions listed above. 

1. Write-enable the volume. 

2. Respecify /DO, /RT, or /RS correctly. 

3. No recovery is possible with the volume currently mounted. 
Mount a volume that is in the proper format and retry the 
operation . 

4. Reenter the command line. 



FLX — FILE ALREADY EXISTS 

Explanation: The specified output file already exists on the 
output device. 

User Action: Reenter the file specification using a new or 
corrected file name. 



FLX — FILE NOT FOUND 

Explanation: The named file does not appear, as specified, in 
the requested directory. 

User Action: Retry the operation with the file name and 
directory correctly specified. 



FLX — WARNING — INPUT FILE OUT OF SEQUENCE 

Explanation: A multivolume cassette file is being accessed out 
of sequence. 

User Action: This is a warning message. The transfer will 

continue unless you terminate it by means of the ABORT command. 



FLX — @ FILE NESTING EXCEEDED 

Explanation: More than one level of indirect command file was 
specified . 

User Action: Reenter the command line with only one level of 
indirect command file specified. 
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FLX — @ FILE SYNTAX ERROR 

Explanation: A syntax error occurred in the indirect command 
file. 

User Action: Edit the indirect command file. Rerun FLX using 

the corrected indirect command file. 



FLX — FMTD ASCII RECORD FORMAT BAD 

or 

FLX — FMTD BrNARY RECORD FORMAT BAD 

Explanation: Either the file is corrupted or is not of the 
specified type. 

User Action: If the file is corrupted, no recovery is possible. 
If the file type is incorrect, reenter the command line 
specifying the correct transfer mode switch. 

FLX — ILLEGAL /BS SIZE — USE 0<N<=512. AND EVEN 

Explanation: An illegal block size was specified with /BS on 
cassette output. 

User Action: Reenter the command line with a legal block size. 

FLX — INCORRECT # IN/OUT SPECS 

Explanation: More than one input or output specification in a 
command was entered where only one is allowed. 

User Action: Reenter the command line with the proper syntax. 

FLX — INVALID DEVICE 

Explanation: A device was specified that cannot be used for the 
purpose specified. For example, a line printer was specified as 
an input device. 

User Action: Reenter the command line with a valid device 
specified . 

FLX — INVALID DOS OR RT-11 FILE SPEC 
or 

FLX — INVALID RSX FILE SPEC 

Explanation: The file specification does not conform to proper 
syntax or the specified operation could not be performed on the 
specified device. 

User Action: Reenter the command line with the proper syntax. 
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FLX — INVALID SWITCH 

Explanation: A switch was entered that is not a valid FLX switch 
or does not conform to proper syntax. 

User Action: Reenter the command line with a correct switch 
specification . 

FLX — I/O ERROR 

Explanation: One of the following conditions may exist: 

• The specified device is off-line. 

• A hardware error occurred (for example, bad tape) . 

User Action: Ensure that the device is on-line. Reenter the 
command line. If a hardware error recurs, recovery may not be 
possible. 

FLX — I/O ERROR DELETING LINKED FILE 

Explanation: An uncorrectable error occurred while a DOS linked 
file was being deleted. 

User Action: No action required. The file is effectively 
deleted, but the volume may be corrupted. 

FLX — I/O ERROR INITIALIZING DIRECTORY 

Explanation: One of the following conditions may exist: 

• The specified device is not on-line. 

• The specified volume is not mounted. 

• A hardware error occurred (for example, bad tape) . 

User Action: Ensure that the device is on-line and is operable. 
Reenter the command line with the required switch specified. 

FLX — I/O ERROR ON COMMAND INPUT 

Explanation: An unexpected error in command input was 
encountered from either an indirect command file or from the 
initiating terminal; FLX exits. 

User Action: Restart FLX. 
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FLX — I/O ERROR ON FLX TEMPORARY FILE 

Explanation: FLX encountered an error condition with its 
temporary file. FLX creates a temporary file on SYO: for 
operations involving DOS-11 CT, DT, or MT volumes. This error 
occurs when one of the following conditions exists: 

• SYO: is not on-line and mounted. 

• SYO: is wr i te-locked . 

• A protection violation occurred. 

• A hardware error was encountered. 

User Action: Correct the error condition and reenter the command 
1 ine . 

FLX — I/O ERROR ON LIST FILE 

Explanation: An error occurred on the output device during a /DI 
or /LI operation. There is a hardware problem with the output 
device (for example, a device powered down). 

User Action: Correct the condition. Reenter the command line. 



FLX — OUTPUT DEVICE FULL 

Explanation: The DOS-11 or RT-11 output volume does not contain 

enough space for the output file. 

User Action: Delete all unnecessary files and reenter the 
command line. 



FLX — OUTPUT FILE SPEC NOT ALLOWED 

Explanation: An output file specification was entered for an 
operation that does not allow one. 

User Action: Reenter the command line without an output file 
specification. 



FLX — RECORD TOO LARGE 

Explanation: FLX detected an input record in a Files-11 transfer 
that is larger than the specified or implied record size for the 
file; that is, the file is corrupted. 

User Action: The file in question is unusable. 
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FLX — REQUEST TERMINATED — LAST BLOCK NOT WRITTEN 

Explanation: A carriage return was given to indicate that no new 
volume would be mounted when an end-of-volume was encountered on 
cassette output. The block that FLX was attempting to write when 
it encountered the end of the cassette has not been written. 
Therefore, the output file is incomplete. 

User Action: This message is informational. No action is 
requi red . 



FLX — WARNING — SPECIFIED RECORD SIZE BAD, 512. USED 

Explanation: The record size n specified with the /FA, /FB, or 
/IM switch is not acceptable. A record size of 512(10) bytes is 
assumed . 

User Action: This is a warning message. No action is required. 



FLX — UNABLE TO ALLOCATE FILE 

Explanation: No space is available on the DOS-11 or Files-11 
volume for the specified file. 

User Action: Delete all unnecessary files and reenter the 
command line. 



FLX — UNABLE TO OPEN FILE 

Explanation: A specified input or output Files-11 file could not 
be opened. Possible reasons are: 

• The input file does not exist. 

• The volume is not mounted. 

• A protection violation occurred. 

User Action: Correct the condition and reenter the command line. 



FLX — UNABLE TO OPEN LIST FILE 

Explanation: The list file cannot be opened under the specified 
file name and directory, or the specified volume may not be a 
valid Files-11 volume. 

User Action: Reenter the command line specifying the correct 
file name and directory. 
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FLX — UNDIAGNOSABLE REQUEST 

Explanation: FLX does not recognize the command line syntax. 
User Action: Reenter the command line with the proper syntax. 

FLX — /CO FILES FROM INPUT DEVICE NOT ALLOWED UNLESS BL: SPEC 

Explanation: When transferring files from MT r PR, or CT volumes, 
the /CO switch can only be specified when the /BL switch is also 
specified . 

User Action: Reenter the command line, specifying the /BL 
switch. 

FLX — * IN VERSION NUMBER NOT ALLOWED 

Explanation: A wildcard was detected in the version number field 
of a file specification. 

User Action: Reenter the command line with all version numbers 
explicitly specified. 

FLX — ILLEGAL DENSITY VALUE 

Explanation: Either the specified density value is not supported 
by the target tape drive or some value other than 800, 1600 or 
6250 was input. 

User Action: Reenter the command with the proper density value. 
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CHAPTER 5 
DISK VOLUME FORMATTER (PMT) 



The Disk Volume Formatter (FMT) utility formats and verifies disk 
cartridge, disk pack, fixed media disk, and flexible disk volumes 
under any RSX-11M or RSX-11M-PLUS operating system that includes on 
line formatting support in the Executive. (Check with your system 
manager to determine whether your system includes this feature.) 

In general, FMT performs the following functions: 

• Writes a complete header for each sector of the volume it is 
formatting . 

• Verifies the address contents of each sector header. 

• Sets the density for RX02 floppy disks (DY) . 

• Lets you specify an error limit for the volume being 
formatted. FMT terminates processing when the error limit is 
reached . 

• Lets the Bad Block Locator task (BAD) run (spawn) if your 
system permits spawned tasks. 



5.1 INITIATING AND TERMINATING FMT 

To initiate FMT, enter the appropriate command following the system 
monitor prompt, as explained in Chapter 1 of this manual. 

The general form of the FMT command line is: 

>FMT ddn: [/switch 1... /switch m] 

The variable dd is the abbreviation for the volume you are formatting 
and n is the unit number of the volume. The possible switches are: 

/BAD 

Runs the Bad Block Locator task (BAD) if it is installed on the 
system. 

Note that the /BAD switch can only be used with operating systems 
that allow spawning of tasks. RSX-11M provides spawned tasks as 
a system generation option. RSX-11M-PLUS always includes support 
for spawned tasks. 
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/DENSITY or /DENS 

Selects high (double) or low (single) density for RX02 floppy 
disks . 

/ERL 

Determines the number of errors FMT will allow on the volume. 
/MANUAL or /MAN 

Enters manual operating mode and formats the sector or track you 
specify. 

/NOVERIFY or /NOVE or /-VERIFY or /-VE 

Inhibits the default verification of a successful FMT operation. 

/OVR 

Overrides or ignores the Manufacturer's Defined Bad Sector File 
(MDBSF) . 

/WLT 

Rewrites the MDBSF (on the last track of the device) to add bad 
sectors found during FMT operation. 

/VERIFY or /VE 

Verifies that an FMT operation was successfully completed. This 
switch is the default. 

/§Y 

Informs FMT that it is receiving input from an indirect command 
file that you have created. A FMT command in this form does not 
allow operator intervention in the process. 

These switches are described in detail in Section 5.4. 

To terminate FMT, type CTRL/Z (~Z) following the FMT prompt, as 
explained in Chapter 1 of this manual. 



5.2 MODES OF FMT OPERATION 

FMT lets you format volumes in two operating modes: normal and 
manual. In normal operating mode, FMT formats the entire volume. In 
manual operating mode, FMT permits you to format individual sectors 
(or tracks for DM:-type disks) that you specify in response to FMT 
prompts. FMT uses normal operating mode unless you specify manual 
mode with the /MAN switch in the command line. 

FMT normally retries an operation when it encounters an error. If the 
operation still fails, FMT flags the sector as bad and displays the 
following message: 

Error writing header 
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If FMT encounters an error during the verification operation, it 
prints one of the following messages on your terminal: 

Error reading header 

or 

Header compare error 
FMT then continues the verification operation. 

5.2.1 Normal Operating Mode 

When you invoke FMT in normal operating mode (without the /MANUAL 
switch) , FMT prints the following message: 

** WARNING - Data will be lost on ddn: ** 
Continue? [Y or N] 

CAUTION 

If you answer yes, FMT erases all data 
previously stored on the disk. 

After a Y (yes) response, FMT returns the message: 
Start formatting 

It then performs the formatting functions you specify with switches in 
the FMT command. After an N (no) response or a carriage return, FMT 
returns control to the system monitor. 

Normal FMT operation varies slightly according to the volume you are 
formatting (see Section 5.3). 

5.2.2 Manual Operating Mode 

If you specify manual operating mode (/MAN), FMT prints: 

** WARNING - Data will be lost on ddn: ** 
Continue? [Y or N] 

CAUTION 

If you answer yes, FMT erases all data 
previously stored on the disk. 

After a Y (yes) response, FMT returns the message: 

Entering manual mode 

It then displays the following prompts: 

Cyl inder= 
Track 
Sector = 
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After you enter your response to the prompts, FMT formats the sector 
or track you specify. FMT assumes the responses are in decimal unless 
they are preceded by a pound sign (#) to indicate an explicit octal 
response. If you enter a parameter that is out of the range for the 
volume, FMT returns an error message and exits. Table 5-1 lists the 
valid ranges for FMT manual mode operations. 

Note that FMT manual operating mode cannot be used with RX02 floppy 
disks. 

FMT manual operating mode works the same on all disk volumes, with one 
exception: On DM:-type volumes (RK06 and RK07) , FMT formats a 
specific track. 

For example: 

FMT>DM 0: /MAN 

This command causes FMT to prompt: 

** WARNING - Data will be lost on DM0: ** 
Continue? [Y or N] Y 

Entering manual mode 
Cylinder= 237 
Track = 1 

FMT then formats the entire track you specified. 



Table 5-1 
Ranges for Manual FMT Operations 



Devicel 


Sectors 


Tracks 


Cyl inders 


RP02/RPR02 


0-9 


0-19 


0-199 


RP03 


0-9 


0-19 


0-3 99 


RP04 


0-21 


0-18 


0-410 


RP05 


0-21 


0-18 


0-410 


RP06 


0-21 


0-18 


0-814 


RK05/RK05F 


0-11 


0-1 


0-199 


RK06 


0-21 


0-2 


0-410 


RK07 


0-21 


0-2 


0-814 


RM02 


0-31 


0-4 


0-822 


RM03 


0-31 


0-4 


0-822 


RM05 


0-31 


0-18 


0-822 


RM80 


0-31 


0-13 


0-558 
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5.3 FMT SUPPORTED DISK VOLUMES 

The following sections describe using normal FMT operating mode with 
the different types of FMT supported devices. Table 5-2 lists the 
disk volumes that allow formatting and their device mnemonics. 



Table 5-2 
FMT-Supported Disk Volumes 



Disk Volumes 


Device Mnemonic 


RP04 disk pack 


DB: 


RP05 disk pack 


DB: 


RP06 disk pack 


DB : 


RK05 disk cartridge 


DK: 


RK05F fixed media disk 


DK: 


RL01 disk cartridge 


DL: 


RL02 disk cartridge 


DL: 


RK06 disk cartridge 


DM: 


RK07 disk cartridge 


DM: 


RPR 02 disk pack 


DP: 


RP02 disk pack 


DP: 


RP03 disk pack 


DP: 


RM02 disk pack 


DR: 


RM03 disk pack 


DR: 


RM05 disk pack 


DR: 


RM80 fixed media disk 


DR: 


RX02 floppy disks 


DY: 



The status FMT requires for the disk volumes varies with the operating 
system. On an RSX-11M operating system, the disk volume must be 
unmounted . 

On an RSX-11M-PLUS operating system, the disk volume must be mounted 
with foreign characteristics (MOUNT/ FOREIGN) . 



5.3.1 DB:-type Devices (RP04/RP05/RP06 Disk Packs) 

When FMT formats a DB : -type volume, it tries to write 22 sector 
headers at a time until it has formatted the entire volume. If FMT 
encounters an error, it attempts to write each header individually and 
designates which headers are bad. 

Unless you specify the /-VE switch, FMT verifies 11 headers at a time 
until it has verified the volume. If FMT encounters an error, it 
attempts to verify the headers individually to determine where the 
error occurred. It then reports any bad headers and continues the 
operation . 
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5.3.2 DK:-type Devices (RK05 Disk Cartridge or RK05F Fixed Media Disks) 

When FMT formats a DK: -type volume, it tries to write each sector 
header individually until it has formatted the entire volume. If FMT 
encounters an error, it retries each header before reporting the 
header as bad. 

Unless you specify the /-VE switch, FMT verifies 12 headers at a time 
until it has verified the volume. If FMT encounters an error, it 
attempts to verify the headers individually to determine where the 
error occurred. It then reports any bad headers and continues the 
operation . 



5.3.3 DL:-type Devices (RL01/RL02 Disk Cartridges) 

FMT does not format a DL:-type volume, but reads each block, one track 
at a time, and determines which blocks were marked as bad by the 
manufacturer's formatting process. If the MDBSF is corrupt or has 
been written over, FMT then rewrites the Manufacturer Detected Bad 
Sector File (MDBSF) on the last track with this information. When 
using FMT on a DL:-type device, the Write Last Track switch (/WLT) 
must be specified. 



5.3.4 DM:-type Devices (RK06/RK07 Disk Cartridges) 

FMT writes DM:-type headers one track (22 sectors) at a time and sets 
the header flags of those sectors marked bad in the MDBSF. If FMT 
encounters errors, it retries the operation before it designates which 
headers are bad. 

Unless you specify the /-VE switch, FMT verifies that each sector from 
to 21 is addressable. It does this by issuing a full 256-word 
write, made up of the 2-word address pattern (the sector number and 
its complement) into each sector. Once the track has been written, 
each sector is read and the full 256 words of data are compared with 
the expected data pattern. If an error occurs during this operation, 
FMT reports that sector as bad and continues the operation. 

When FMT writes headers on DM:-type devices, it sets bad sector flags 
in the headers already marked as bad in the MDBSF. Unless you specify 
the /-VE switch, FMT indicates whether the bad sector was flagged in 
the MDBSF. 



5.3.5 DP:-type Devices (RPR02/RP02/RP03 Disk Packs) 

When FMT formats a DP: -type volume, it tries to write 10 headers at a 
time until it has formatted the volume. If FMT encounters an error, 
it attempts to write each header individually and designates which 
headers are bad. 

Unless you specify the /-VE switch, FMT verifies 10 headers at a time 
until it has verified the volume. If FMT encounters an error, it 
attempts to verify the headers individually to determine where the 
error occurred. FMT reports that sector as bad and continues the 
operation. 
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5.3.6 DR:-type Devices (RM02/RM03/RM05/RM80 Disk Packs) 

When FMT formats a DR:-type volume, it tries to write 32 headers at a 
time until it has formatted the volume. If FMT encounters an error, 
it attempts to write each header individually and designates which 
headers are bad. 

Unless you specify the /-VE switch, FMT verifies 16 headers at a time 
until it has verified the volume. If FMT encounters an error, it 
attempts to verify the headers individually to determine where the 
error occurred. It then reports any bad sectors and continues the 
verification operation. 

When FMT writes headers on DR:-type volumes, it sets bad sector flags 
in headers already designated as bad by the MDBSF. Unless you specify 
the /-VE switch, FMT indicates whether the sector was marked bad in 
the MDBSF. 

On the RM80 disk, in addition to performing the functions indicated 
for other DR: devices, FMT reads a Skipped Sector File to identify 
the sectors the manufacturer's formatter designated as "skipped 
sectors," and then sets the skipped sector flag bit in the appropriate 
sector headers. All data originally intended for a sector designated 
as a skipped sector is moved to the following sector (for more 
information, see the RSX-11M/M-PLUS I/O Drivers Reference Manual) . 



5.3.7 DY:-type Devices (RX02 Floppy Disks) 

You can use FMT to set an RX02 floppy disk to either high (double) or 
low (single) density by using the /DENS switch. Unless you specify 
the /-VE switch, FMT writes and reads block and the last block on 
the disk to determine that the density is consistent. 

Note that manual operating mode cannot be used with DY:-type devices. 



5.4 FMT SWITCH DESCRIPTIONS 

The following sections describe the switches you can use with FMT 
commands. The descriptions include information on restrictions for 
formatting specific devices and default values for the switches, where 
appropriate . 

/BAD 

The Bad switch spawns the Bad Block Locator task (BAD) after FMT 
completes its processing. The BAD operation tests for the number 
and location of any unusable blocks. BAD records this bad-block 
information which is used by the initializing function. If BAD 
is not installed on the system, FMT prints a warning message on 
your terminal and exits. 

Note that the /BAD switch can only be used with operating systems 
that allow spawning of tasks. RSX-11M and RSX-11M-PLUS provide 
spawned tasks as a system generation option. 

The format for an FMT command using the /BAD switch is: 

FMT>ddn:/BAD 
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/DENSITY 

The Density switch sets DY:-type floppy disks to either high 
(double) or low (single) density. The default is low density. 
(This switch can also use SINGLE and DOUBLE as options.) 

The formats for an FMT command using the /DENS switch are: 

FMT>DYn :/DENS=HIGH (or DOUBLE) 
FMT>DYn :/DENS=LOW (or SINGLE) 

/ERL 

The Error Limit Switch sets an error limit for the volume you are 
formatting. If the error count reaches this limit, FMT generates 
an appropriate message and terminates the operation. The default 
error limit is 256(10) errors. Any value greater than or less 
than or equal to 256(10) is valid. 

The format for an FMT command using the /ERL switch is: 
FMT>ddn :/ERL=n . 

/MANUAL 

The Manual switch puts FMT in manual operating mode and permits 
you to format an individual sector (or track for DM:-type disk 
cartridges) of a device. FMT assumes cylinder, track, and sector 
numbers are decimal values unless they are preceded by a pound 
sign (#), which indicates octal values. 

Note that manual operating mode cannot be used with DY:-type 
devices . 

In manual operating mode, FMT displays the following prompts: 



** WARNING - Data will be lost on ddn: ** 

Continue [Y OR N]? 
Entering manual mode 
Cyl inder= 
Track 
Sector = 

Operation complete 
The format for an FMT command using the /MAN switch is: 
FMT>ddn:/MAN 

/NOVERIFY 

The Noverify switch inhibits the operation performed by the 
default /VERIFY switch. 

The format for an FMT command using the /NOVERIFY switch is: 
FMT> ddn :/NOVERIFY 



5-8 



DISK VOLUME FORMATTER (FMT) 



/OVR 

The Override switch causes FMT to ignore the Manufacturer's 
Detected Bad Sector File (MDBSF) on DM:- and DR:-type disk 
volumes. When FMT writes headers on these disks, it normally 
sets bad sector flags in those headers marked bad in the MDBSF. 
When the verification process discovers a bad sector, it reports 
that the sector was marked in the MDBSF. The Override switch 
inhibits the reporting operation. 

The format for an FMT command using the /OVR switch is: 
FMT>ddn:/OVR 

/VERIFY 

The Verify switch confirms that an FMT operation was successful. 
It does this by reading back the headers and determining that 
they were written correctly. This switch is the default. 

The format for an FMT command using the /VE switch is: 

FMT>ddn:/VE 

/WLT 

The Write Last Track switch, when used with the Verify switch on 
DM:- and DR:-type volumes, rewrites the MDBSF to add the bad 
sectors that FMT found to the bad sectors already in the MDBSF. 
FMT also rewrites each bad sector's header to flag it as a bad 
sector . 

The /WLT switch must be specified when using FMT on a DL:-type 
dev ice . 

The /WLT switch requires a decimal number (n below) which is used 
as the volume's pack serial number. 

The format for an FMT command using the /WLT switch is: 
- FMT>ddn :/WLT=n 

/@Y 

If you specify the @Y switch, FMT receives input from an indirect 
command file that you have created. In this method of operation, 
FMT will not generate any operational messages or warnings to 
your terminal. No user intervention is possible until the FMT 
operation is complete. 

The format for an FMT command using the /@Y switch in an indirect 
command file is: 

FMT ddn:/@Y 

Note that to run FMT from an indirect command file, FMT must be 
installed before hand. Otherwise, you will receive an error 
message and the FMT operation will discontinue. 
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Example 



To format a DK: -type volume using an indirect command file, 
create the indirect command file FMTIND.CMD (you can specify any 
file name) which contains the following: 

FMT DK3:/@Y 

Then issue the following indirect command from the prompt: 
>@FMTIND 

FMT will start to format the disk, DK3: and the /@Y switch will 
inhibit any FMT message from printing on your terminal until 
after FMT has finished. 



5.5 FMT MESSAGES 

This section describes the messages FMT generates, and possible user 
responses . 

Command I/O error 

Explanation: A hardware transmission error occurred from the 
keyboard . 

User Action: Reenter the command. 

Command too long 

Explanation: The command was longer than 80(10) characters. 
User Action: Enter a shorter command. 

Device does not support formatting 

Explanation: A device was specified that does not allow the use 
of FMT. 

User Action: Determine the correct device and, if FMT operation 
is legal, reenter the command. 

Device driver missing 

Explanation: The disk device driver is not loaded. 

User Action: Load the driver (if it is loadable) and reenter the 
command, or use a different device in the command line. 

Device not in system 

Explanation: The specified device was not identified as part of 
the system during system generation or the device does not exist 
on the system hardware configuration. 

User Action: Determine the correct command line with the correct 
device mnemonic and reenter the command. 



5-10 



DISK VOLUME FORMATTER (FMT) 



Device not ready 

Explanation: The disk volume was not at operating speed when FMT 
attempted to access it. 

User Action: Allow the volume to reach operating speed, then 
reenter the FMT command. 



Device offline 

Explanation: The device is not in the system hardware 
configuration . 

User Action: Determine the correct command line with the correct 
device abbreviation and reenter the command. 



Device write locked 

Explanation: The volume is wr ite-locked ; any write access is 
prohibited . 

User Action: Write-enable the unit and reenter the FMT command. 



Disk is an alignment cartridge 

Explanation: The device is a factory-created disk used to align 

the heads in a disk drive and should not be used for other 
purposes . 

User Action: Use a disk that is not an alignment cartridge and 
reenter the FMT command. 



Error limit exceeded 

Explanation: The number of errors FMT found on the disk exceeded 
either the number of errors specified with the /ERL switch or the 
default 256(10) error limit that FMT sets. 

User Action: Set a higher error limit if the /ERL switch was 
used . 



Error reading data 

Explanation: FMT encountered an error when it tried to read data 
from a disk. 

User Action: None required. FMT retries the operation and 

continues the verification. 



Error reading header 

Explanation: FMT encountered an error when it tried to read a 
header during a verification operation. 

User Action: None required. FMT retries the operation and 
continues the verification. 



5-11 



DISK VOLUME FORMATTER (FMT) 



Error setting diskette density 

Explanation: FMT tried to format a RX02 floppy disk but the 
operation failed. 

User Action: Check the syntax and reenter the command, resetting 
the density. 

Error writing data 

Explanation: FMT encountered an error when it tried to write 
sector headers. 

User Action: None required. FMT retries the operation and 
continues the verification. 

Error writing header 

Explanation: FMT encountered an error when it tried to write a 
header . 

User Action: None required. FMT retries the operation. 

Failed to attach device 

Explanation: FMT could not attach the device to be formatted. 

User Action: Determine whether another task has attached the 
device. If so, wait until the task exits or abort the task and 
run FMT again. 

Failed to read Manufacturer's Bad Sector File 

Explanation: A disk hardware error occurred while FMT tried to 
read the MDBSF on the last track of a device. 

User Action: Reenter the command, including the Override switch 
(/OVR). 

Fatal hardware error 

Explanation: A fatal error occurred in the system hardware 
configuration . 

User Action: Contact your DIGITAL Field Service representative. 

Header compare error 

Explanation: FMT found an error when it tried to compare headers 
with the expected value during a verification error. 

User Action: None required. FMT retries the operation. 
Invalid switch 

Explanation: An illegal switch or a switch not valid for the 
specified device was used in an FMT command. 

User Action: Check the syntax and reenter the command. 
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Manufacturer's Bad Sector File corrupt * 

Explanation: The factory-written bad block data file (MDBSF) on 
the last track of the disk is in an unusable format. 

User Action: Reenter the command with the Override switch (/OVR) 
to prevent FMT from trying to use the corrupt bad block data. 



Marked bad in Manufacturer's Bad Sector File 

Explanation: Indicates that bad block information is recorded in 
the MDBSF on the disk. 

User Action: None required. This message is for your 
information only. 



Privilege violation 

Explanation: FMT attempted an operation on a device that was 
mounted or allocated to another user. 

User Action: Reenter the FMT command, using a device that is not 
mounted or allocated to another user. 



Response out of range 



Explanation: Parameters entered for manual formatting of an 
individual sector or track were out of the range for the volume. 

User Action: Check Table 5-1 (Section 5.2.2) for valid 
parameters and reenter the command. 



Syntax error 

Explanation: FMT detected a syntax error in the command line. 

User Action: Determine the correct command syntax and reenter 
the command . 



Unable to run badblock utility 

Explanation: An FMT command specified the Bad switch (/BAD), but 
BAD could not be spawned. Either the operating system does not 
spawn tasks or BAD is not installed. 

User Action: Run the BAD utility separately (see Chapter 6 for 
more information) . 



Unrecoverable error - n 

Explanation: An I/O error (number n) caused FMT to terminate. 

User Action: Reenter the FMT command and, if the error occurs 
again, try the command specifying a different device, or refer to 
the error codes in the IAS/RSX-11 I/O Operations Reference 
Manual . 
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BAD BLOCK LOCATOR UTILITY (BAD) 



The Bad Block Locator Utility (BAD) tests disks and DECtapes for the 
location and number of bad blocks. BAD then records this bad block 
information on the volume. Then you use the MCR Initialize Volume 
command (INI), which allocates the bad blocks to the file 
[0, 0]BADBLK. SYS. The bad blocks are marked as in-use and therefore 
cannot be allocated to other files. 

BAD supports any last-track device as well as vendor-supplied 
cartridges that do not have a prerecorded manufacturer's bad-sector 
file on the last track (see Sections 6.4.1.1 and 6.4.1.2). You can 
use BAD in its task version, which runs at the same time as other 
tasks, or in its stand-alone version ( [ 1 , 51 ] BADS YS . SYS ) , which runs by 
itself on the computer. The stand-alone version is required if you 
have a system with a single disk drive. 



6 . 1 BAD COMMAND FORMAT 

The command line for BAD is in the following format: 
BAD>dev : [/sw] . . . 



dev 

Specifies a physical device. The specification consists of two 
alphanumeric characters followed by a 1- to 3-digit octal unit 
number and colon. 



/sw 

Specifies an optional switch that qualifies the BAD command line. 
Multiple BAD switches for a device must be specified on one line. 
If you do not specify any switch, BAD begins its pattern checking 
of individual blocks. 



6 . 2 BAD SWITCHES 

Table 6-1 contains a reference list of BAD switches along with a brief 
description of each. For a detailed description of BAD switches see 
Section 6.6. 
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Table 6-1 
BAD Switches 



Switch 


Function 


For Task 


and Stand-Alone Versions 


/ALLOCATE : volume label 
or /ALO: volume label 


Prompts you for blocks to be allocated 
to BADBLK. SYS and to be entered in the 
bad block descriptor file. 


/LIST 
or /LI 


Lists bad blocks as they are located. 


/MANUAL 
or /MAN 


Prompts you for additional bad blocks 
which are entered in the bad block 
descriptor file. 


/OVERRIDE 
or /OVR 


Creates the bad block descriptor file on 
a last-track device. 


/PATTERN=m -n 

or /PAT=m:n 


S*n p ri f i p f- K a H nuhl p wci t ft ^aj-a tdzi ffprn 

used to locate bad blocks. 


/RETRY 


Recovers soft errors. 


/UPDATE 
or /UPD 


Reads the bad block descriptor file 
and prompts for input. 


For Stand-Alone Version Only 


/CSR=nnnnnn 


Specifies the CSR address of a device 
that is not in a standard location. 


/VEC=nnn 


Specifies the interrupt vector address 
of a device that is not in a standard 
location . 


/WCHK 


Causes a write check. 


/NOWCHK 


Negates /WCHK. 



6.3 BAD AND INDIRECT COMMAND FILES 

BAD can access an indirect command file that contains a series of BAD 
command lines in the following manner: 

BAD>@BADCMDS . CMD 

In this example, BAD is invoked and accesses the file BADCMDS.CMD, 
which contains a sequence of BAD command lines. BAD executes the 
comands and returns with the BAD prompt. BAD allows nested command 
files — one command file can invoke another to a maximum depth of 
three . 
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BAD can also be invoked within an indirect command file. Such a 
command file can contain command lines for more than one utility and 
is accessed by entering only the file specification preceded by the at 
sign. For example: 

>@INDIRECT.CMD 

The default values for indirect command file specifications are: 

dev SYO: 

ufd The current UIC 

file name No default 

file type . CMD 

version The latest version of the file 

For complete information on how to use indirect command files, see the 
RSX-11M/M-PLUS MCR Operations Manual. 



6.4 PROCESSING BAD BLOCK DATA 

This section contains information on how BAD tests the reliability of 
disks and DECtapes and formats bad block descriptor entries and how 
the MCR INI command uses bad block information. 



6.4.1 Verifying Devices 

BAD verifies disks and DECtapes by writing a test pattern onto each of 
the blocks on the device, reading the pattern into a buffer in memory, 
and comparing the pattern written with the pattern read. When BAD 
processes a disk or DECtape, all existing data is destroyed. 

BAD writes the test pattern to several blocks in a single write 
operation. If an error occurs in writing, reading, or comparing any 
of these blocks, BAD tests each of the blocks individually. The 
/PATTERN switch may be used to specify the double-word test pattern. 
Its default values are 165555(8) and 133333(8), which are replicated 
128(10) times per block. If BAD finds no bad blocks during individual 
testing, the error logging subsystem may still log errors due to long 
data transfers. 



6.4.1.1 BAD and Non-Last-Track Devices - As BAD locates bad blocks, 
it stores their addresses in a memory buffer. After locating all bad 
blocks on a device, BAD records the addresses of the bad blocks on the 
last good block of the device. Consecutive bad blocks are recorded as 
single entries. On non-last-track devices, BAD storage allows 126(10) 
entries of bad block addresses. If more than the maximum number of 
entries is recorded, BAD terminates with an error message. There must 
be at least one good block in the last 256(10) blocks of the volume 
for BAD to create this file, which is called the bad block descriptor 
file. 



6.4.1.2 BAD and Last-Track Devices - BAD records bad block 

information differently on last-track devices than on non-last-track 
devices. Last-track devices include the RK06/07, RL01/02, RP07 and 
the RM 02/0 3/0 5/8 0. The last track is divided into two areas, the 
Manufacturer's Detected Bad Sector File (MDBSF) and the Software 
Detected Bad Sector File (SDBSF) . The MDBSF is created when the 
manufacturer formats the pack. This operation also sets bits in any 
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header that is marked bad in the MDBSF and sets the SDBSF to be empty. 
When you run BAD, entries are made in the SDBSF. BAD storage allows 
126(10) entries of bad block addresses. The information contained in 
the two last-track files is combined to form [0, 0]BADBLK. SYS when you 
issue the MCR INI command. 



6.4.2 Format of Bad Block Descriptor Entries 

For non-last-track devices, BAD uses the last good block as a 
descriptor file for bad blocks. The address of a bad block, or the 
first address in a sequence of consecutive bad blocks, is stored as a 
double-word entry in the bad block descriptor file. The first word of 
this double-word contains two entries: the high-order byte contains 
the number of bad blocks minus 1 and the low-order byte contains bits 
16 through 23 of the logical block number of a bad block or a range of 
bad blocks. The second word of the double-word contains bits 
through 15 of that block number. 

For last-track devices, bad block descriptor entries are recorded as a 
double-word in the SDBSF. The first word of the double word contains 
the address of the cylinder on which the bad block exists. The 
high-order and low-order bytes of the second word contain, 
respectively, the track and sector addresses of the bad block. 



6.4.3 The INI Command and BAD 

Use BAD followed by the MCR INI command to produce a Files-11 volume. 
The INI command uses the bad block information to create the file 
[0, 0]BADBLK. SYS. The [0,0] BADBLK. SYS file has allocated to it those 
blocks found to be bad, thus ensuring that the file system does not 
allocate a known bad block to a file. 

For information on how to use the INI command, see the RSX-11M/M-PLUS 
MCR Operations Manual. 



6. 5 USING BAD 



Before BAD can validate a device, that device must be formatted by the 
manufacturer or by FMT (see Chapter 5). 

On an RSX-11M system, the volume must not be mounted. Issue the MCR 
Dismount command if the device contains a mounted volume. 



On an RSX-1 1M-PLUS system, the volume must be mounted as foreign. 

The following example illustrates a typical sequence of steps for 
introducing a disk (DK1 : ) to an RSX-11M or RSX-11M-PLUS system. 



RSX-1 1M Commands 

ALL DK1: (H) 

FMT DK1: [/sw] © 

BAD DK1: [/sw] W) 

INI DK1: [label] [/sw] © 

MOU DK1: [label] [/sw] (ret) 



RSX-1 lM -PLUS Commands 

ALL DK1: (H) 

MOU DK1:/F0R © 

FMT DK1: [/sw] © 

BAD DK1: [/sw] ® 

INI DK1: [label] [/sw] (H) 

DMOU DK1: (ret) 

MOU DK1: [label] [/sw] W) 
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You may execute BAD while other RSX-11M/M-PLUS tasks are executing. 

Note that if the /ALO switch (Section 6.6.1) is used with BAD, the 
volume must be mounted as a Files-11 device and the user must have a 
privileged account. 



6.5.1 Programming Considerations 

This section contains information you should know before you use BAD. 



6.5.1.1 Use of Block Zero - On bootable disks, block zero contains 
the bootstrap block. If block zero is bad, BAD prints a message 
warning the operator not to use the disk for a bootable system image. 



6.5.1.2 Device Controller Errors - The error logging subsystem may 
log errors even though BAD is not reporting bad blocks. These errors 
may be encountered during long data transfers and may originate with 
the device controller. 



6.6 BAD SWITCH DESCRIPTIONS 

The following sections describe the switches you can use with BAD 
commands. The command format is described in Section 6.1. 



6.6.1 Switches for Both Task and Stand-Alone Versions of BAD 

/ALLOCATE: volume label 

Causes BAD to prompt you for additional bad blocks which are 
added to the bad block descriptor file and allocated to [0,0] 
BADBLK. SYS. The /ALLOCATE switch eliminates the need to 
reinitialize the disk after updating the bad block descriptor 
file. This switch does not cause BAD to write pattern checks. 



NOTE 

To use this switch, the volume must be 
mounted as a Files-11 device and the 
user must be privileged. 



/LIST 

Causes all bad blocks to be printed by number (in decimal) on 
your terminal. The bad blocks are listed as BAD performs a data 
pattern check on each block. BAD does not list manually entered 
blocks that are tested as reliable. This switch is valid for all 
devices . 
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/MANUAL 

Causes BAD to first prompt you for bad block information and to 
then perform data pattern checking. Any block that you enter is 
included in the bad block descriptor file or the SDBSF. 



/OVERRIDE 

Causes BAD to ignore last track information and write a bad block 
descriptor file on the last good block before the last track. In 
other words, the /OVERRIDE switch causes BAD to treat a 
last-track device as a non-last-track device. If your device has 
no bad block file on the last track, or if you suspect the 
reliability of the last track, use the /OVERRIDE switch before 
using the MCR INI command. The /OVERRIDE switch is valid only 
for last-track devices. 



NOTE 

If you use this switch, the /BAD=[OVR] 
option for initializing a volume must 
also be used with the INI command to 
construct the bad block file 
[ , 0] BADBLK. SYS . See the RSX-1 1M/M-PLUS 
MCR Operations Manual for a description 
of the MCR INI command. 



/PATTERN =m:n 

Causes BAD to locate bad blocks by means of a user-specified 
double word data pattern. 

The variable m:n represents the two 16-bit octal numbers used as 
the double word data pattern. A decimal number may be specified 
by placing a period after the number. 



/RETRY 

Causes BAD to attempt a recovery of hardware errors by means of 
the device driver. This also means that soft errors, such as an 
ECC (Error Correction Code) correctable error, will be recovered 
and the block will be marked as good. 



/UPDATE 

Causes BAD to immediately read the bad block decriptor file and 
prompt you for additional bad blocks. This switch does not cause 
BAD to write pattern checks. 



NOTE 

Updating the bad block descriptor file 
on file-structured volumes does not 
cause the file [ 0, 0] BADBLK. SYS to be 
updated . 

Examples of the /MANUAL, /ALLOCATE and /UPDATE Switches, which require 
user input, are described in the following sections. 
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6.6.2 The /MANUAL, /ALLOCATE and /UPDATE Switches: Examples 

If you enter bad blocks by using the /MANUAL, /ALLOCATE or /UPDATE 
switches, BAD will prompt you as follows: 

BAD>LBN(S)= 

You may then enter bad blocks in the format: 
b 1 oc kn urn : number 

The variable number specifies the number of sequential bad blocks 

beginning at the specified block number blocknum. The colon is 

required when you specify a sequence of bad blocks in this format. 

Both blocknum and number default to decimal values unless preceded by 

a pound sign (#), which indicates an octal value. For example: 

BAD>LBN(S)=7 0: 3© 

This command enters the block numbers 70, 71, and 72 in the bad block 
descriptor file. If you are using the /ALLOCATE switch, the blocks 
are also allocated to [0, 0]BADBLK. SYS. 

You can also specify a single bad block. For example: 

BAD>LBN(S)=3(H) 

This command enters block 3 in the bad block descriptor file. The 
/ALO switch also allocates block 3 to BADBLK. SYS . 

You can use both of these forms on the same command line. For 
example : 

BAD>LBN (S ) = 100: 2, 3, 200: 100 45:1 

This command enters blocks 100, 101, 3, 200 through 299, and 45 in the 
bad block descriptor file. The /ALO switch also allocates these 
blocks to [0,0] BADBLK. SYS. You can separate bad block sequences with 
a space, tab, or comma. 

If you are using the Manual or Update switches, and enter a carriage 
return in response to the prompt, BAD will list all the sequences in 
the bad block descriptor file. For example: 

BAD>LBN(S)= m 

000100: 002 

000003: 001 

000200: 100 

000045: 001 
BAD>LBN(S)= 

The first number in the display represents the beginning block of the 
sequence. The second number represents the number of bad blocks. Bad 
block numbers are listed in decimal. 
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If you are using the /ALLOCATE switch and enter a carriage return in 
response to the prompt, BAD will list all the LBNs allocated to 
BADBLK. SYS before it will list the LBNs in the bad block descriptor 
file. For example: 

BAD>LBN(s)=(H) 

LBNs allocated to BADBLK. SYS = 

004799: 001 
000100: 002 
000003: 001 
000200: 001 

LBNs in BAD BLOCK File = 

000100: 002 
000003: 001 
000200: 001 
000045: 001 

BAD> LBN (s) = 

In this example, LBNs 100, 101, 003, and 200 are allocated to [0,0] 
BADBLK. SYS, as is LBN 4799 which is the LBN for the bad block 
descriptor file on this particular disk. Note that the LBN for the 
bad block descriptor file does not appear in the Bad Block file. 
However, this disk has one LBN (LBN 45) which is contained in the Bad 
Block file but is not yet allocated to [0,0] BADBLK. SYS. You can now 
allocate LBN 45 by entering it in response to the LBN(s)= prompt. 
(The "Duplicate block number" message will appear because the LBN 
already exists in the Bad Block file.) 

When a bad block sequence is entered, BAD determines if these bad 
blocks are adjacent to an already existing sequence. If you are using 
a non-last-track device, BAD appends your bad block entry to the 
existing sequence. If you are using a last-track device, BAD records 
individual bad blocks in core memory, but lists entries at your 
terminal as part of existing bad block sequences. 

When you have finished supplying information for the /MANUAL, 
/ALLOCATE, or /UPDATE switch, enter ESCAPE, ALTMODE, or CTRL/Z in 
response to the prompt. The bad block descriptor file will then 
either be rewritten with the new bad block information (if you are 
using the /UPDATE or /ALLOCATE switch) or pattern checking will start 
(if you are using the /MANUAL switch) . Blocks that you enter manually 
and that BAD decides are reliable are included in the bad block 
descriptor file. 



6.6.3 Switches for Stand-Alone System Version Only 

/CSR=nnnnnn 

The variable nnnnnn is a new CSR address. 

This switch allows you to specify the CSR address of the device 
so that it conforms to that of the device in the user's system. 
The /CSR switch remains in effect and need not be repeated if 
more command lines are issued. 
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/VEC=nnn 

The variable nnn is a new interrupt vector address. 

This switch allows you to specify the interrupt vector address so 
that it conforms to the vector address of the device in the 
user's system. The /VEC switch remains in effect if more command 
lines are issued. 



/WCHK 

This switch causes a write-check operation to occur after each 
write operation. The switch is not available for DT : -, DX: -, or 
DY:-type devices. 



/NOWCHK 

This switch negates the /WCHK switch. 

BAD expects to see all switches on a single command line. For 
example : 

BAD>DM3:/OVR/LI/VEC=3 00/CSR=174406 

This command line locates all bad blocks on DM3:, ignores the 
last-track data, lists all bad blocks, specifies 300 as the interrupt 
vector, and specifies 174406 as the CSR address. All switches are 
validated for proper syntax before the actual bad block detection 
takes place. 



6.7 DEVICES SUPPORTED BY BAD 

The devices in Table 6-2 are supported by the stand-alone version of 
BAD. If you have a task version of BAD, the Executive will support 
any device suitable to your system's configuration. 



Table 6-2 

Devices Supported by Stand-alone BAD 



Mnemonic 


Type 


CSR 


Vector 


DB 


RP04/05/06 


176700 


254 


DD 


TU58 DECtape II 


175600 


300 


DF 


RF11 Fixed-Head Disk 


177460 


204 


DK 


RK03/05/05F Cartridge Disk 


177404 


220 


DL 


RL01/RL02 Cartridge Disk Pack 


174400 


160 


DM 


RK06/07 Cartridge Disk Pack 


177440 


210 


DP 


RPR02/RP02/03 Disk Pack 


176714 


320 1 



1. Nonstandard Vector Address , 

(continued on next page) 
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Table 6-2 (Cont.) 
Devices Supported by Stand-alone BAD 



Mnemonic 


Type 


CSR 


Vector 


DR 


RM02, and RM03, 

RM05, RM80, RP07 Disk Pack 


176700 


340 1 


DS 


RS03/04 


172040 


310 1 


DT 


TU56 DECtape 


177342 


214 


DU 


RA80 Fixed Media Disk 


177510 


154 


DX 


RX01 Floppy Disk 


177170 


264 


DY 


RX02 Floppy Disk 


177170 


350 1 


EM 


ML11 Electronic Memory 


172000 





1. Nonstandard Vector Address 



6.8 BAD MESSAGES 

This section lists the BAD messages, gives a brief description of the 
condition that causes each message, and suggests a response to the 
condition. BAD messages are arranged alphabetically beginning with 
the text following the device symbol (ddu:). 



BAD — ddu: Allocation Failure 

Explanation: BAD failed to allocate the block number sequence 
you entered. The I/O failed for a reason other than because the 
block number was already allocated to another file. This message 
applies to the /ALLOCATE switch only. 

User Action: Either the volume is bad or the drive requires 
maintenance. Use another volume or contact your DIGITAL Field 
Service Representative to fix the drive. 



BAD — ddu: Bad block file not found 

Explanation: The bad block descriptor file could not be read in 
/UPDATE mode. 

User Action: You must use the device without updating the bad 
block file, or reformat the device and destroy all data. 



BAD — ddu: Bad block file overflow 

Explanation: BAD detected more than 126(10) entries of bad 
blocks. This message usually indicates a device unit failure. 

User Action: Either the volume is bad or the drive requires 
maintenance. Use another volume or contact your DIGITAL Field 
Service Representative to fix the drive. 
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BAD — ddu: Bad block found - LBN= nnnnnn. 

Explanation: Bad blocks are reported in this format, where LBN 
is the Logical Block Number (decimal). 

User Action: None. This message is informational and applies to 
the /LI switch only. 



BAD — ddu: Block already allocated - LBN= numb 

Explanation: The block number sequence you entered is already 
allocated to a file (the file may or may not be BADBLK. SYS ) . The 
value numb is the sequence you entered. The block sequence 
indicated by numb and list of block numbers which follow numb 
were neither allocated to [0 f 0]BADBLK. SYS nor entered into the 
bad block descriptor file. This message only applies to the 
/ALLOCATE switch. 

User Action: Reenter the command line with another value. 

BAD — ddu: Block bad - Do not use as system disk 

Explanation: This is a warning message. When block zero is bad, 
a bootstrap block cannot be written on the disk, making it 
useless as a system disk. 

User Action: Label the disk to ensure that no one attempts to 
use it as a system disk. 

BAD — Command I/O error 

Explanation: BAD did not recognize the command line entered from 
the keyboard. 

User Action: Reenter the command line. 

BAD — Command too long 

Explanation: The command was longer than 80. characters. 
User Action: Reenter the command line. 



BAD — ddu: CSR address not in system 

Explanation: Self-explanatory. This message occurs only in the 
stand-alone system version of BAD. 

User Action: Reenter the command line, specifying the proper 
value for the /CSR switch. 



BAD — ddu: Device offline 

Explanation: In the stand-alone version of BAD, the specified 
device is not in the hardware configuration, or the /CSR switch 
is improperly set. 

User Action: Reenter the command line, setting the CSR and 
Vector addresses for the device to the proper addresses. 
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BAD — Duplicate block number - numb 

Explanation: The block number sequence you entered is already 
present in the bad block file. The value numb is the sequence 
you entered. BAD ignores any block number sequences you may have 
entered after the duplicate block numbers. 

This message applies only to the /ALLOCATE, /MANUAL and /UPDATE 
switches. If this message appears when using the /ALLOCATE 
switch, it means that the block number which was allocated to 
[0, 0]BADBLK. SYS already existed in the bad block descriptor file. 

User Action: Reenter the command line with another value. This 
message applies to the /MANUAL, /ALLOCATE and /UPDATE switches 
only. 



BAD — ddu: Failed to attach 

Explanation: BAD could not gain control of the device to be 
tested . 

User Action: Determine if another task has attached the device. 
If so, wait until the task exits or abort the task to gain 
control of the device for BAD. 



BAD — ddu: Failed to read BADBLK. SYS header 

Explanation: Self-explanatory. This message only applies to the 
/ALLOCATE switch. 

User Action: The disk must be initialized using the MCR INI 
command . 



BAD — ddu: Failed to read Manufacturer's Bad Sector File 

Explanation: A disk-read hardware error occurred while BAD was 
attempting to read the factory-written bad block data on the 
last-track device cartridge. 

User Action: Reenter the command line with the /OVERRRIDE switch 
included . 



BAD — ddu: Failed to read Software Bad Sector File 

Explanation: The software-detected bad sector file could not be 
read in update mode. 

User Action: Reenter the command line with the /OVERRIDE switch 
included . 



BAD — ddu: Failed to write Bad Block File 

Explanation: BAD could not write the bad block file. This 
condition usually results from a disk write error. 

User Action: Reenter the command line. If the problem persists, 
the disk pack should be discarded. 



6-12 



BAD BLOCK LOCATOR UTILITY (BAD) 



BAD — ddu: Fatal hardware error 

Explanation: Self-explanatory. 

User Action: Contact your DIGITAL Field Service representative. 

BAD — ddu: Handler/Driver missing 

Explanation: The disk driver is not loaded. 

User Action: Load the disk driver and reenter the command line. 

BAD — ddu: Home block not found 

Explanation: BAD was unable to read the home block while 
attempting to validate the volume label. This message only 
applies to the /ALLOCATE switch. 

User Action: The disk must be initialized using the MCR INI 
command . 

BAD — ddu: Illegal device 

Explanation: The device to which bad block processing is 
directed does not support a Files-11 structure. 

User Action: You must reformat your device before running BAD. 

BAD — Invalid block number - numb 

Explanation: You entered an invalid block number sequence. The 
value numb is the invalid sequence. 

User Action: Type another value and reenter the command line. 
This message applies to the /MANUAL, /ALLOCATE or /UPDATE 
switches only. 

BAD — Invalid switch 

Explanation: Self-explanatory 

User Action: Reenter the command line with a proper switch. 

BAD — ddu: Is an alignment cartridge 

Explanation: The factory-written label on the last track of a 
last-track device cartridge indicates an alignment cartridge (for 
use only by Field Service) . 

User Action: Mount and process another cartridge. 

BAD — ddu: Manufacturer's Bad Sector File corrupt 

Explanation: The factory-written bad block data in the last 
track of a last-track device is in an inconsistent format. 

User Action: Reenter the command line with the /OVERRIDE switch 
included . 
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BAD — ddu: Not in system 

Explanation: The requested device was not made part of the 
system during system generation, or the device does not exist on 
the host configuration. 

User Action: Ensure that you entered the command line correctly 
and specified the right device. 



BAD — ddu: Not ready 

Explanation: The unit had not reached operating speed when BAD 
attempted to access it. 

User Action: Allow the unit to reach operating speed, then 
reenter the command line. 



BAD — ddu: Privilege violation 

Explanation: An operation was attempted for a device that was 
mounted or allocated to another user. 

User Action: Allocate another device, mount the device (if 
necessary), and reenter the command line. 



BAD — Syntax error 

Explanation: BAD detected a syntax error on the command line. 

User Action: Determine the correct syntax and reenter the 
command line. 



BAD — ddu: Total bad blocks = n. 

Explanation: This is an information message indicating the total 
number (in decimal) of bad blocks on the volume. 

User Action: Write the bad blocks count on the volume label. 



BAD — ddu: Unrecoverable error n 

Explanation: An I/O error caused BAD to terminate. The value 
[n] is the error code number of the I/O error returned by the 
driver . 

User Action: See the IAS/RSX-11 I/O Operations Reference Manual 
for an explanation of the error code number. If the same error 
persists, contact your DIGITAL Field Service represent ive . 



BAD — ddu: Vector not multiple of four 
Explanation: Self-explanatory. 

User Action: Reenter the command line including the /VEC switch 
with the proper value. 
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BAD — ddu: Volume label incorrect 

Explanation: The volume label entered with the /ALLOCATE switch 
did not match the label on the disk. 

User Action: Reenter the command line using the correct volume 
label . 

BAD — ddu: Write locked 

Explanation: The unit is wr ite-locked . 

User Action: Write-enable the unit and reenter the command line. 
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CHAPTER 7 
BACKUP AND RESTORE UTILITY (BRU) 



The Backup and Restore Utility (BRU) allows you to back up and restore 
Files-11 volumes. You can use BRU to transfer files from a volume to 
a backup volume (or volumes) to ensure that a copy of the files is 
available in case the original files are destroyed. If the original 
files are destroyed, or if for any other reason the copy needs to be 
retrieved, you can restore the backup files with BRU. In the process 
of copying, BRU also reorganizes and compresses files for efficient 
storage and access. 

You can use BRU stand-alone as well as on-line. BRU64K is the 
stand-alone version on RSX-11M and BRUSYS is the stand-alone version 
on RSX-11M-PLUS. 

Backup and restore operations take place on disk and magnetic tape 
volumes : 

• Disk to tape — for backup operations 

• Tape to disk — for restore operations 

• Disk to disk — for either backup or restore operations 

In addition to these basic data transfer functions, BRU provides 
command qualifiers that: 

• Initialize disks 

• Perform selective backup and restore operations 

• Control tape processing such as density, length, rewinding, 
appending, and labeling according to the American National 
Standard (ANS) X. 327-1978 

• Perform volume and data checking 

• Display information such as backup set names and file names 

Section 7.9 contains examples of various BRU operations. 

BRU can also be invoked through the DCL BACKUP command. For more 
information, see the RSX- 1 1M/M- PLUS Command Language Manual . 



7.1 ON-LINE BRU DISK AND TAPE DEVICE INFORMATION 

BRU uses disk and tape volumes for its backup and restore operations. 
Input disks must be in Files-11 format. For tapes and multivolume 
backup disks, BRU has its own format. 
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BRU backs up from unmounted, mounted, and mounted foreign disk 
volumes . 

BRU does not use the file system on input disks. However, when you 
are using a mounted volume for a backup operation, BRU checks the read 
access privileges of UFDs and files against the UIC under which BRU is 
running. To back up from a mounted disk volume that is in Files-11 
format, you must specify the /MOUNTED qualifier. For unmounted disks 
or disks mounted foreign, no qualifier is necessary. 

BRU also restores to unmounted and mounted disk volumes. Specify the 
/INITIALIZE qualifier to restore to an unmounted volume on an RSX-11M 
system or a volume mounted foreign on an RSX-11M or M-PLUS system. 
This qualifier initializes the volume to Files-11 format. To restore 
to a mounted Files-11 volume on either system, specify the 
/NOINITIALIZE qualifier to indicate to BRU that the disk is mounted 
and already in Files-11 format. 

BRU backs up to and restores from tape volumes. The tapes must be 
unmounted or mounted foreign on RSX-11M or mounted foreign on 
RSX-11M-PLUS . No qualifier is necessary in either case. 

Table 7-1 summarizes how to initialize and mount a volume on each 
system. BRU returns an error message for any wrong combination of 
conditions . 



Table 7-1 
Mounting and Initializing Volumes 



System 


Volume 


Mount Status 


Mandatory Qualifier 


RSX-11M 


Input disk 


Not mounted 
Mounted Files-11 
Mounted foreign 


None 

/MOUNTED 
None 




Output disk 


Not mounted 
Mounted Files-11 
Mounted foreign 


/INITIALIZE 

/NOINITIALIZE 

/INITIALIZE 




Input tape/ 
output tape 


Not mounted 
Mounted foreign 


None 
None 


RSX-11M-PLUS 


Input disk 


Mounted foreign 
Mounted Files-11 


None 

/MOUNTED 




Output disk 


Mounted foreign 
Mounted Files-11 


/INITIALIZE 
/NOINITIALIZE 




Input tape/ 
output tape 


Mounted foreign 


None 



For more detailed information on Files-11, refer to the IAS/RSX-11 I/O 
Operations Reference Manual . 

With BRU, you can also specify that a disk volume contain up to 65,500 
(64K-36) files. The default is the value assigned to the input disk. 
See the descriptions of the /HEADERS and /MAXIMUM qualifiers in 
Section 7.4 for more information. 
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7.1.1 Backup Sets 

A backup set consists of all the 
disk volume (or volumes) during 
Physically, more than one backup 
disk, or a backup set can extend 



data directed to or from a tape or 
a single backup or restore operation, 
set may be contained on a tape or 
over several tapes or disks. 



7.1.2 Tape Sets and Disk Sets 

More than one backup set can be contained on a tape or disk, or a 
backup set can extend over several tapes or disks. In either case, 
the resulting output is called a tape or disk set. 

A tape or disk set consists of the tape or disk volume (or volumes) to 
which data is transferred during a single backup operation. 



7.1.2.1 Tape and Disk Backup Operations - There are several 
classifications of disk and tape backup operations to choose from. 
You can classify a backup operation by how much of the original tape 
or disk you are backing up and also by the format of the output 
medium. 

The following backup operations are available to you: 

• Full backup 

• Selective backup 

• Conventional backup 

• Image backup (for disks only) 

A full backup or a selective backup refers to the files you are 
backing up. A conventional backup or an image backup refers to the 
format of the output tape or disk. When you choose to do either a 
full backup or a selective backup, you may or may not also choose to 
do a conventional backup or an image backup. 

The following sections explain the different kinds of backup 
operations . 



7.1.2.2 Full and Selective Backup Operation - A full backup transfers 
all the original files to a backup volume (or volumes). Thus, a full 
backup ensures that you have a complete copy of the original disk. 

A selective backup is a partial backup. If you do a selective backup, 
a subset of the original tape or disk is backed up. You select and 
identify the files to be backed up by UFD, date, or file 
specification. 

One type of selective backup is the incremental backup. An 
incremental backup is a backup of files by date only. Incremental 
backups and selective backups are helpful over a short time span when 
a full backup would take up too much time or system resources. 
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7.1.2.3 Conventional Backup Operation - A conventional backup to tape 
copies the files from the original disk to a backup set on a BRU 
format tape. The backup set can span multiple tapes and you can 
append additional backup sets to a volume (or volumes) . You cannot 
access the files in the backup set directly. Therefore, you must 
restore the backup set to disk before you can access the individual 
files contained in it. 

A conventional backup to disk copies the files from the original disk 
to another Files-11 disk. You can access the files on the input disk 
or the output disk directly, eliminating the need to do a restore 
operation . 

If the output disk already has a Files-11 structure, you can add the 
files from the original disk. If the output disk does not have a 
Files-11 structure, you must use BRU with the /INITIALIZE qualifier to 
create a Files-11 structure on the output disk. 



7.1.2.4 Image Backup to Disk Operation - An image backup to disk 
copies the original disk to a container file on another Files-11 disk 
(or disks). Image backups are used for multivolume backup operations. 

A disk container file has features similiar to features of tapes 
created by a conventional backup to tape. A disk container file can 
span multiple disks, and you can add several backup sets to a 
container file. 

If you want to do a backup operation, you must specify the SAVE option 
with the /IMAGE qualifier. If you want to do a restore operation, you 
must specify the RESTORE option with the /IMAGE qualifier. In order 
to access the files in a backup set, you must restore the backup set 
to another disk. (See Section 7.4 for a description of command 
qualifiers . ) 

If the output disk already has a Files-11 structure, you can add the 
container file to it. If the output disk does not have a Files-11 
structure, BRU creates its own structure on the disk with the 
container file. 



7.1.3 Multivolume Tape and Disk Operations 

When you specify a magnetic tape drive as the output device or when 
you specify a disk for an image backup in a BRU operation, BRU 
transfers the data contents of the input disk to the tape or disk on 
the drive. This data transfer often involves more than one reel of 
tape or more than one disk and may use more than one tape or disk 
drive . 

You can specify more than one type of drive in a single BRU command. 
However, although you can specify up to eight drives per command, you 
can specify an individual tape or disk drive only once. 

If the number of volumes required exceeds the number available, BRU 
lets you replace tapes or disks on the specified drive in round-robin 
fashion . 

You can only use all 7-track or all 9-track tapes in a multivolume 
tape set. You cannot switch from one track type to the other within 
the set. 
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You can only use the same disk types when backing up to multiple disk 
in image mode. You cannot mix disks. 

7.1.4 Supported Devices 

Table 7-2 lists all the devices that on-line BRU supports. The disks 
from DB through EM are all block-structured devices. 



Table 7-2 
Devices Supported by On-Line BRU 



Mnemonic 


Type 


DB 


RH11/RP04/RP05/RP06 or RH70/RP04/RP05/RP06 disk 
pack 


DD 


TU58 cassette (DECtape II) 


DF 


RF11/RS11 fixed head disk 


DK 


RK11/RK05/RK05F cartridge pack 


DL 


RL11/RL01/RL02 cartridge disk 


DM 


RK611/RK06/RK07 cartridge disk 


DP 


RP11/RP02/RP03 disk pack 


DR 


RH70/RM03/RM05/RM80/RP07 or RH11/RM02 disk pack 


DS 


RH11/RS03/RS04 or RH70/RS03/RS04 fixed head disk 


DT 


TC11/TU56 DECtape 


DU 


RA80/RA60/RA81/RC25/RD51/RX50 disk 


DX 


RX11/RX01 floppy disk 


DY 


RX211/RX02 floppy disk 


EM 


ML11 electronic memory 


MF 


TM78/TU78 magnetic tape 


MM 


RH11/TM02-03/TE16/TU16/TU45/TU77 and 
RH70/TM02-03/TE16/TU16/TU45/TU77 
9-track magnetic tape 


MS 


TS11/TSV05/TU80 magnetic tape 


MT 


TM11/TE10/TU10 7- or 9-track magnetic tape or 
TS03 9-track magnetic tape 



7.2 COMMAND LINES 

This section describes the rules for entering command lines for BRU. 
The section defines the command line syntax and describes prompts, 
command line parameters, and command qualifiers. 
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7.2.1 Command Line Syntax 

BRU command lines have a maximum length of 256(10) characters except 
in one case of using continuation lines (see Section 7.2.2.2). The 
general syntax of the BRU command line is: 

BRU>/qualif ier (s) indevicel :,...[ f ilespec , ... ] outdevicel : , . . . 

However, if you type only 

>BRU RH 

the following three prompts appear on the terminal: 
FROM: 
TO: 

INITIALIZE [Y/N] : 

FROM 

Requests that you enter the name (or names) of the devices on 
which the input volume (or volumes) reside. The names should 
be in the form specified in the description of the command line 
parameters (see Section 7.2.2). If you want, you may specify a 
UIC, but this is not required. 

TO 

Requests that you enter the name (or names) of the output 
devices. The names should be in the form specified in the 
description of the command line parameters (see Section 7.2.2). 
The UIC should not be specified in the command line because BRU 
tries to copy the entire UIC. 

INITIALIZE [Y/N] 

Enter Y (for YES) if you want to initialize the output volume. 

Enter N (for NO) if you do not want to initialize the output 
volume . 

There is no default answer. You must respond with either Y or 
N. 



7.2.2 Command Line Parameters 

The parameters for BRU command lines are qualifiers, device 
specifications, and file specifications. 

/qualifier (s) 

Specifies any of the command qualifiers listed in Section 7.3. 
If two or more qualifiers are specified, they must be 
contiguous, that is, separated with a slash only. The 
qualifiers can appear in any order. 

You can use a shorter form of a qualifier as long as it is 
unique. All BRU qualifiers are unique to three characters. 
For example: 

BRU>/REW/INI/OUT:BACKUP MMO : DBO : 



7-6 April 1983 



BACKUP AND RESTORE UTILITY (BRD) 



When a qualifier has options, you must separate the qualifier 
from the option by a colon in the form: 

/qual i f ier : opt ion 

indevice 

Specifies the physical device (or devices) from which data is 
transferred. For tapes and for disks (if you are using the 
/IMAGE qualifier) you can specify more than one input device 
and more than one type of drive. Devices are specified in the 
form : 

dd [nn] : 

The variable dd represents the device mnemonic and nn 
represents the octal unit number associated with that device. 
The unit number is specified as one or two digits; the default 
unit number is 0. For example, a TU77 tape drive can be 
referenced as MMO0:, MMO : , MM: , MM01 : , MM1 : , and so forth, 
depending on your configuration. The colon is a required 
del imi ter . 

Separate the device specifications with commas when you specify 
more than one device. 

f ilespec 

Indicates the file specification used to select particular 
files or categories of files to be backed up or restored. The 
file specification is in the following format: 

[ufd] filename . filetype; version 

You can specify up to 16(10) file specifications in each 
command line. When you enter a command line with no file 
specifications, all the files on the input volume are copied to 
the output volume. 

Files can be backed up or restored selectively by UFD, file 
name, file type, or version number. When backing up or 
restoring selectively by version number, you must specify 
either an explicit version number or no version number at all 
or a wildcard (*) . The wildcard has the same effect as no 
version number. BRU does not support or -1 as version 
numbers . 

outdevice 

Specifies the output device to which data is being transferred. 
For tapes and for disks (if you are using the /IMAGE qualifier) 
you can specify more than one output device. The form is the 
same as for indevice (described previously) . 



7.2.2.1 Wildcards in Input Specifications - The following wildcard 
(*) features are provided for input file UFD specifications: 

[*,*] means all group, member combinations, 
[nl,*] means all member numbers for group nl. 
[*,n2] means all group numbers for member n2. 

BRU also supports the wildcard in the remaining elements of a file 
specification: file name, file type, and version number. BRU 
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generally follows the rules for use of wildcards (see the 
RSX-11M/M-PLUS MCR Operations Manual ) , except in the following two 
instances : 

• When you omit a file specification element, BRU treats the 
omitted element as if it were a wildcard. For example, when 
you specify only file name and file type in a file 
specification, all version numbers are transferred in the 
backup or restore operation. However, when you omit the 
UFD, it defaults to your current UIC. 

• When you specify particular UFDs on a command line but do 
not specify file names and/or file types, all the files in 
those UFDs are transferred in the backup or restore 
operation. That is, you do not have to specify [ufd]*.*. 



7.2.2.2 Continuation Lines - BRU command lines have a maximum 
length of 256(10) characters. BRU allows you to continue a command 
line onto more than one line by using a hyphen (-) as the 
continuation character. 

On RSX-11M systems, BRU supports continuation lines only when you 
invoke BRU and then respond to the BRU> prompt. BRU does not 
support continuation lines when run from an indirect command file or 
when you enter the command line on the same line as the one on which 
you invoked BRU. 

On RSX-1XM-PLUS systems, BRU supports continuation lines under all 
circumstances. However, when you use BRU from the MCR command 
level, the total number of characters for the initial command line 
and any subsequent continuation lines cannot exceed 80. 

Section 7.9 gives examples of continuation lines on RSX-11M and 
RSX-11M-PLUS. * 



7.3 SUMMARY OF COMMAND QUALIFIERS, OPTIONS , AND DEFAULTS 

Table 7-3 lists the command qualifiers available for backup and 
restore operations. For a detailed explanation of each qualifier, 
see Section 7.4. Examples of using various qualifiers are given in 
Section 7.9. 



Table 7-3 
Summary of BRU Command Qualifiers 



Command Qualifiers 


Options 


Default 


/APPEND 

/BACKUP SET: name 




None 

Volume name 
of the disk 
being backed 
up 



(continued on next page) 
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Table 7-3 (Cont.) 
Summary of BRU Command Qualifiers 



Command Qualifiers 


Options 


Default 


/BAD : 


MANUAL 

AUTOMATIC 

OVERRIDE 


BAD '.AUTOMATIC 


/BUFFERS: number 




Number of 
FCBs from the 
input disk 


/COMPARE 




None 


/CREATED: 


BEFORE: (dd-mmm-yy hh:mm:ss) 

BEFORE : dd-mmm-yy 

BEFORE : hh :mm : ss 

AFTER: (dd-mmm-yy hh:mm:ss) 

AFTER: dd-mmm-yy 

AFTER:hh :mm:ss 


Current date 


/DENSITY :number 




Default 
density of 
drive 


/DIRECTORY 




None 


/DISPLAY 




None 


/ERRORS : number 




/ERRORS: 25. 


/EXCLUDE 




None 


/EXTEND: number 




Number of 
blocks from 
the input 
disk 


/HEADERS : number 




Number of 
headers 
al located 
to the input 
vol ume 


/IMAGE: 


SAVE 
RESTORE 


None 


/INITIALIZE 




None 


/INVOLUME:name 




None 


/LENGTH: number 




The length of 
the output 
tape 



(continued on next page) 
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Table 7-3 (Cont.) 
Summary of BRU Command Qualifiers 



Command Qualifiers 


Opt ions 


Def aul t 


/MAXIMUM: number 




Max imum 
number of 
files allowed 
on input the 
volume 


/MOUNTED 




None 


/NEW_VERSION 




/NOSUPERSEDE 


/NOINITIALIZE 




None 


/NOPRESERVE 




None 


/NOSUPERSEDE 




/NOSUPERSEDE 


/OUTVOLUME:name 




Input disk 
volume name 


/POSITION: 


BEGINNING 

MIDDLE 

END 

BLOCK: number 


Index file 
position on 
the input 
disk 


/PROTECTION: 


SYSTEM:value 
OWNER:value 
GROUP:value 
WORLD : val ue 


Protection of 
the input 
disk 


/REVISED : 


BEFORE : (dd—mmm-yy hh:mm:ss) 

BEFORE: dd-mmm-yy 

BEFORE : hh :mm : ss 

AFTER: (dd-mmm-yy hh:mm:ss) 

AFTER: dd-mmm-yy 

AFTER :hh :mm :ss 


Current date 


/REWIND 




None 


/SUPERSEDE 




/NOSUPERSEDE 


/TAPE LABEL: label 




None 


/UFD 




None 


/VERIFY 




None 


/WINDOWS: value 




Number of 
mapping 
pointers on 
the input 
disk 



7-10 



BACKUP AND RESTORE UTILITY (BRU) 



7.3.1 Command Qualifier Functions 

When you initialize a disk using the BRU /INITIALIZE qualifier, use 
the following qualifiers to specify various characteristics for the 
output disk. 

/BAD 

/BUFFERS 
/EXTEND 
/HEADERS 
/MAXIMUM 



/NOPRESERVE 

/OUTVOLUME 

/POSITION 

/PROTECTION 

/WINDOWS 



The /MOUNTED command qualifier allows you to copy files from a mounted 
disk . 

The following command qualifiers allow you to copy files to a mounted 
disk with various results. Note that these qualifiers are not 
available in stand-alone BRU (see Section 7.5). 

/NEW_VERSION 

/NOINITIALIZE 

/NOSUPERSEDE 

/SUPERSEDE 

/UFD 

The following command qualifiers allow you to backup or restore data 
according to: 

• File specification 

• Date and time of creation 

• Date and time of revision 
The qualifiers are: 

/CREATED 
/EXCLUDE 
/REVISED 



The following qualifiers allow you to control backup and restore tape 
processing : 

/APPEND /LENGTH 

/BACKUP_SET /REWIND 

/DENSITY /TAPE_LABEL 

/ERRORS 
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The following command qualifiers allow you to detect differences 
between data on the input volume and data on the output volume: 

/COMPARE 

/INVOLUME 

/VERIFY 



The /DIRECTORY and /DISPLAY command qualifiers display information 
about the files being transferred. 



The /IMAGE command qualifier is for both disk image backups and all 
restore operations. 



7.4 DESCRIPTIONS OF COMMAND QUALIFIERS 

The following paragraphs describe the BRU command qualifiers in 
detai 1 . 

/APPEND 

Directs BRU to append a backup set from the input disk volume to 
the last backup set on the output tape, or on the output disk if 
you are using the /IMAGE qualifier. 

If the output tape was positioned at the beginning the /APPEND 
qualifier causes BRU to skip to the logical end-of-tape before it 
writes the new backup set. BRU searches the output volume for 
the last logical end-of-file. 

If the output tape is already positioned at the logical 
end-of-tape, /APPEND causes BRU to start writing where the device 
is currently positioned. 

If the output tape is not positioned at the beginning, or if it 
is not at the logical end-of-tape, you can use the /REWIND 
qualifier with /APPEND to rewind the tape and then space forward 
until the logical end-of-tape. 

If the tape is a continuation tape (that is, not the first tape 
in a set) or if the last backup set does not end on the tape, BRU 
displays an error message. 

If the output device is a disk and you are using the /IMAGE 
qualifier, /APPEND causes BRU to check the container file header 
for the logical end-of-file on the output disk. BRU then starts 
writing at the logical end-of-file. 

If the output disk is a continuation disk (that is, not the first 
disk in a set) or if the last backup set does not end on the 
disk, BRU displays an error message. 

You cannot use the /APPEND qualifier during a backup operation to 
a mounted disk. 
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/BACKUP_SET : name 

Specifies the name of the backup, set (refer to Section 7.1.1) to 
be placed on tape or disk. For tape and for an unmounted disk, 
the default name is the volume name of the disk being backed up. 
This name may be up to 12(10) characters long. For a mounted 
input or output disk during an image backup or restore operation, 
you can specify the full backup set file name with the 
/BACKUP_SET qualifier. If you do not specify the file name, the 
default is [0 ,0] BACKUP. SYS. 

When applied to an output volume, the backup set name assigns the 
name; of the backup set being placed on the volume. BRU supports 
multiple backup sets on a single volume. 

When this qualifier is applied to an input tape volume, BRU 
searches the first tape for the specified backup set name. If 
you do not specify a backup set name with the input volume, BRU 
restores the first backup set it finds on the tape. You can 
restore several sequential backup sets from the same tape without 
rewinding the tape between BRU operations. BRU does not rewind 
the first device in a backup set unless you specify the /REWIND 
qualifier . 

When this qualifier is applied to an input disk volume, BRU 
searches the entire disk for each backup set you specify. Each 
backup set is then restored in the order of the backup set names 
you provided. 



/BAD: AUTOMATIC 
OVERRIDE 
MANUAL 



The /BAD qualifier creates the file BADBLK . SYS on the output 
disk. The qualifier is used with the /INITIALIZE qualifier 
during tape-to-disk or disk-to-disk operations. 

For complete information on how to use the options for /BAD, see 
Section 7.6. The following are summary descriptions only. 

For last-track devices, the AUTOMATIC option causes BRU to use 
the manufacturer-written bad block information and the 
software-detected bad sector file to create BADBLK. SYS. For 
nonlast-track devices, it uses the software bad block descriptor 
block to create BADBLK. SYS. AUTOMATIC is the default option. 

The OVERRIDE option applies only to last-track devices, causing 
the last-track device to appear to be a nonlast-track device. 
When OVERRIDE is specified, BRU uses the software bad block 
descriptor block to create BADBLK. SYS and ignores the 
manufacturer -writ ten information . 



The MANUAL option accepts the addresses of bad blocks you enter 
interactively at your terminal. It also specifies that BRU use 
either the manufacturer-written bad block information and the 
software-detected bad sector file (for last-track devices) or the 
bad block descriptor block (for nonlast-track devices) to create 
BADBLK. SYS. 



7-13 



April 1983 



BACKUP AND RESTORE UTILITY (BRU) 



/BUFFERS : number 

Specifies the default number of directory File Control Blocks 
(FCBs) on each volume. The FCBs are stored in memory by the 
Ancillary Control Processor (ACP) when the volume is mounted. 
The more FCBs there are stored in memory, the faster that files 
contained in heavily used directories are found. The default 
number of buffers is the same as for the input disk. 

The /BUFFERS qualifier is used with the /INITIALIZE qualifier 
during tape-to-disk or disk-to-disk operations. 

/COMPARE 

Compares the data on the output device with the data on the input 
device and reports any differences. No data transfer takes place 
during a compare operation. The command line specifying the 
compare operation must be identical to that entered when the data 
on the output disk or tape was created, with the exception of the 
/INITIALIZE, /NOINITIALIZE, and /APPEND qualifiers. 

/COMPARE Output 

When the compare operation detects differences, it displays 
a message at your terminal. The compare operation always 
displays the mnemonic of the device on which the difference 
was detected and the type of record in which the difference 
was encountered (a control record, a header record, or a 
data record) . 

If the record type is a header record, the compare operation 
also displays the file-ID for the file. If the record type 
is a data record, the compare operation also displays the 
file-ID, the Logical Block Number (LBN) of the block in 
error, and the name of the file if it is available. 

/CREATED: BEFORE: (dd-mmm-yy hh:mm:ss) 
BEFORE :dd-mmm-yy 
BEFORE :hh :mm:ss 
AFTER: (dd-mmm-yy hh:mm:ss) 
AFTER : dd-mmm-yy 
AFTER :hh:mm:ss 

Backs up or restores files created before or after the specified 
date and/or time. 

If you use the BEFORE option, BRU copies any files created before 
the specified date and/or time. 

If you use the AFTER option, BRU copies any files created on or 
after the specified date and/or at or after the specified time. 

If you specify both a date and a time, the date and time must be 
enclosed in parentheses. If you specify only a date or only a 
time, the parentheses are not necessary. If you specify only a 
time, BRU uses the current date as the default. If you specify 
only a date, the time defaults to 00:00. 

/DENSITY:number 

Specifies the density (bpi) at which BRU writes to tape. The 
following chart shows the values you can specify. 
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Drive 



Default Density 



Optional Density 



TU10/TE10 

TU16/TE16 

TU45 

TU77 

TS11 

TSV05 

TU78 

TU80 



800 
800 
800 
800 
1600 
1600 
6250 
1600 



None 
1600 
1600 
1600 
None 
None 
1600 
None 



If you specify /DENSITY with /APPEND, you must specify the 
density at which the existing tape data was written. For 
example, if the tape was first written at a density of 800 bpi , 
you must specify a density of 800. If you specify a density 
other than the original density, BRU displays a message and 
continues processing at the correct density. 

If you enter an incorrect density for a restore operation, BRU 
displays an error message and terminates the operation. 



/DIRECTORY 



Lists at your terminal the backup set names or files on the 
specified tape or disk volume. In a multivolume tape set, the 
directory is on the first tape of the set. In a multivolume disk 
set, the directory is on the. first disk of the set. 

Using /DIRECTORY to Display Backup Set Names: 

When specified with no backup set name, /DIRECTORY lists all 
the backup sets on the volume: 

BRU> /DIRECTORY MM0 : 

VOL1 BACKUP1 LABEL1 2-JAN-83 
VOL1 BACKUP2 LABEL1 3-JAN-8 3 



BRU> /DIRECTORY DUO: 

VOL1 BACKUP1 LABEL 1 13-JUN-83 
VOL2 BACKUP1 LABEL2 14-JUN-83 

Using /DIRECTORY to Display File Names: 

To display the names of files in a backup set, enter the 
backup set name with /DIRECTORY in the form shown below. 

If the backup set is not on the tape or disk, BRU halts 
execution and displays a message at your terminal. 

An example with tape follows: 



>RUN BRU 

BRU> /BACKUP_SET : 2 3 MAY8 2 A/DIRECTORY MM1 : 

VOL1. 23MAY82A HWHDOC 13-JUN-82 23:37:11 

[000,000] 

[303,013] 

27DECE.LST;1 

2JANA.LST; 1 

18JANC.LST;1 

4JANA.LST;2 
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25DECA.MAC;1 
9DECA.LST; 2 
X . MAC ; 1 
X.OBJ;l 
X.TSK;1 
APNDXC.TXT; 1 
X.MAP; 1 
[001,054] 
RSX11M.STB;45 
[002,054] 
RSX11M.STB;36 
[003,054] 

RSX11M.STB;3 
[005,054] 
[306,006] 
APNDXB . MAC ; 1 
BRU - COMPLETED ON MMl : 

BRU>(CfRDz) 
> 



Prints at your terminal the file name and UFD of each file as the 
header for that file is being transferred by BRU. 

/ERRORS: number 

Terminates a restore operation after the specified number of 
nonfatal tape read errors. The range for number is to 65535. 
The default number of errors before termination is 25(10). 



Backs up or restores all of the files on the tape or disk except 
the files specified on the command line. 

/EXTEND: number 

Specifies the default number of blocks by which a file is 
extended when that file has exhausted its allocated space. This 
value is used by an ACP when the volume is mounted. The default 
is the number of blocks from the input disk. 

The /EXTEND qualifier is used with the /INITIALIZE qualifier 
during tape-to-disk or disk-to-disk operations. 

/HEADERS : number 

Specifies the number of file headers to allocate initially to the 
index file. The primary reason for preallocating file headers is 
to locate them near the storage bitmap file. (The storage bitmap 
file is generally located in the middle of the disk.) Proper 
placement of file headers can help reduce head motion during I/O 
operations. The default is the number of headers allocated to 
the input volume. 

The /HEADERS qualifier is used with the /INITIALIZE qualifier 
during tape-to-disk or disk-to-disk operations. 

If you want to copy files from a disk with a single-header index 
file (structure level 401) to a disk with a multiheader index 
file (structure level 402) , specify a number of file headers with 
/HEADERS and a number of files with the /MAXIMUM qualifier that 



/DISPLAY 



/EXCLUDE 
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are both large enough to make the output disk contain a 
multiheader index file. See the description of the INI command 
in the RSX-11M/M-PLUS MCR Operations Manual for a table of 
maximum and default values. 



/IMAGE: SAVE 

: RESTORE 

Specifies that you want to do a multiple disk-to-disk backup or 
restore operation. If you are doing a backup operation, you 
must specify the SAVE option on the command line. If you want 
to do a restore operation, you must specify the RESTORE option 
on the command line. 



If you want to do a backup operation, you must use this 
qualifier when you create the backup file that represents the 
image copy of the input disk or disks. For example, this 
qualifier must be used when you copy a large disk to several 
small disks, or if you copy several small disks to a mounted 
large disk. 

If you want to do a restore operation, you must use this 
qualifier when restoring from a backup file that represents the 
image copy of the original disk. 



/INITIALIZE 



Specifies that you want to initialize the output disk during a 
tape-to-disk or disk-to-disk operation. Initialization places a 
Files-11 structure on the disk, including the boot block, the 
home block, and such files as INDEXF.SYS, BADBLK . SYS , and 
000000 .DIR. 



The conditions for initializing an output volume differ between 
RSX-11M and RSX-11M-PLUS . BRU returns a privilege violation if 
the conditions are not met satisfactorily (see Table 7-1) . 

On RSX-11M, the volume must be unmounted or mounted foreign. 

On RSX-11M-PLUS, the volume must be mounted foreign. 

Along with the /INITIALIZE qualifier, you can specify the 
following qualifiers when you are initializing a disk: 

/BAD /NOPRESERVE 

/BUFFERS /OUTVOLUME 

/EXTEND /POSITION 

/HEADERS /PROTECTION 

/MAXIMUM /WINDOWS 

If you do not specify any of these qualifiers, BRU defaults to 
the characteristics of the input volume except for the /BAD 
qualifier and the /NOPRESERVE qualifier. For the /BAD qualifier, 
the default is AUTOMATIC. For the /NOPRESERVE qualifier, there 
is no default. 



/INVOLUMErname 



Specifies the volume label of the input disk. This name can be 
up to 12(10) characters long. 

For disk-to-tape or disk-to-disk operations, the /INVOLUME 
qualifier directs BRU to look for the volume label of the input 
volume to verify that the disk has the correct label. This check 
ensures that you do not back up the wrong volume. 
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For restore operations, /INVOLUME directs BRU to check the volume 
label of the disk that is stored in the backup set on tape or in 
the image backup set file on the disk. 

/LENGTH: number 

Specifies the length of the output tape in decimal feet. If the 
length specified exceeds the length of the tape, the entire 
length of the output tape is used. In cases where you know the 
end of a tape must not be used, you can specify a shorter length 
to ensure that you do not write on that part of the tape. 

/MAXIMUM: number 

Specifies the maximum number of files that can be placed on a 
volume as determined by the number of file headers in the 
volume's index file. (BRU supports up to 65,500 files on a 
volume.) The default maximum is the maximum number of files on 
the input disk. The /MAXIMUM qualifier and the /HEADERS 
qualifier are particularly useful when you are initializing an 
output disk that is different in size from the input disk. 

If you want to copy files from a disk with a single-header index 
file (structure level 401) to a disk with a multiheader index 
file (structure level 402) , specify a number of files with 
/MAXIMUM and a number of file headers with the /HEADERS qualifier 
that are both large enough to make the output disk contain a 
multiheader index file. See the description of the INI command 
in the RSX-11M/M-PLUS MCR Operations Manual for a table of 
maximum and default values. 

/MOUNTED 

Allows you to back up files from a disk that is mounted as a 
Files-11 volume (by means of the MCR or DCL MOUNT commands) . If 
you use the /MOUNTED qualifier when the input device is a tape, 
BRU issues a syntax error. 

BRU does not use the file system to read files from the input 
disk. Instead, it issues logical queue I/Os (such as IO.RLB). 
To issue these QIOs to a mounted Files-11 disk, BRU must be built 
as a privileged task (PR:0) . (BRU does not have to be privileged 
for operations on unmounted volumes or volumes mounted foreign.) 
However, when you are restoring to a mounted disk (and you have 
specified the /NOINITIALIZE qualifier) , BRU uses the file system 
to access the output disk. Therefore, a restore operation to a 
mounted disk is slower than a restore to an unmounted disk. 

BRU must also be privileged to back up a disk that is being 
accessed by other users. The /MOUNTED qualifier must be 
specified in the command line. 

When backing up files from a mounted volume, disk activity 
(changes to or addition or deletion of files) while BRU is 
running causes the following results: 

• If the file is being changed while BRU is backing up the 
disk, BRU copies only the data that comprises the file at 
the time of the transfer. Any changes made to the file 
after the transfer will not appear in the file on the 
output volume. 

• If the file is deleted while BRU is backing up the disk, 
the data that comprises the file may be corrupted. 
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If the file-ID from the deleted file is reused in a UFD 
that BRU has not yet backed up, BRU will back up the new 
file (with the previously allocated file-ID) when that 
file is encountered. When restored, this new file (with 
the reused file-ID) will appear as a synonym for the old 
file with the same file-ID. 

• If the disk is changed (files are deleted or changed) 
after BRU generates the directory, the directory on the 
first tape of the tape set or the directory in the backup 
set file on the disk will not be accurate. Because BRU 
generates the directory for the backup set as its first 
processing step, changes to the disk after the directory 
is generated will not be reflected in the directory. 

• If the file or data are being changed during a transfer 
operation, BRU will not be able to verify the accuracy of 
the operation. Do not attempt a verify operation in this 
case . 

Note that this restriction also includes the file being 
used by the error logger. The error logger file changes 
when any hardware errors occur, which can cause the 
verify operation to fail. To ensure that the verify 
operation succeeds, switch the error logger file to a 
different disk or exclude it with the /EXCLUDE qualifier. 

/NEW_VERSION 

Resolves file specification conflicts that occur during restore 
operations and during backups to a mounted disk using the 
/IMAGE:SAVE qualifier. When a file already exists on the output 
disk volume, /NEW_VERSION creates a new version of the file. 

/NOINITIALIZE 

Sp€»cifies that you do not want to initialize the output disk 
because it is already in Files-11 format. The output disk must 
be mounted as a Files-11 volume. You cannot enter any of the 
initialization qualifiers when you specify /NOINITIALIZE. If you 
enter any of these qualifiers, BRU issues an error message. 

/NOPRESERVE 

Specifies that you do not want to preserve file-IDs (file-IDs are 
generally preserved). If you specify the /NOPRESERVE qualifier, 
BRU suppresses the message that file-IDs are not being preserved. 
Note that in restoring to a mounted disk, not preserving file-IDs 
is BRU's default action. /NOPRESERVE is used only with the 
/INITIALIZE qualifier. 

When file-IDs are not preserved, BRU assigns new file-IDs, 
incrementing them sequentially. 

/NOSUPERSEDE 

Specifies that when file specifications on the mounted output 
disk are identical to those on the input volume, the file on the 
input volume is not transferred. That is, the file on the output 
disk is not superseded by the file on the input volume. 
/NOSUPERSEDE is the default. 
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/OUTVOLUME: name 

Specifies the volume label of the output disk. This label can be 
up to 12(10) characters long. 

For disk-to-tape backup operations, the name of the input disk 
volume stored on the output tape volume is changed to the name 
specified with the /OUTVOLUME qualifier. 

For tape-to-disk restore operations or for disk-to-disk 
transfers, the name of the output disk volume is changed to the 
name specified with the /OUTVOLUME qualifier. 

When you omit /OUTVOLUME , BRU provides the following defaults: 

• In backup operations, the input disk volume name is used 
as the volume name stored on the output tape volume. 

• In restore operations, the volume name stored on the 
input tape volume is used as the name of the output disk 
volume . 

• In disk-to-disk transfers, the volume name of the input 
volume is used as the volume name of the output volume. 

/POSITION: BEGINNING 
MIDDLE 
END 

BLOCK: number 

Specifies the location of the index file on the output disk 
volume being initialized, usually to minimize access time. The 
BEGINNING, MIDDLE, and END options specify the beginning, middle, 
and end of a volume. The BLOCK:number option specifies a block 
number where the index file is to be placed. The BEGINNING or 
END option is generally used only when a disk mostly contains 
large contiguous files. MIDDLE is recommended to minimize access 
time . 

When you use the BLOCK:number option, the number is decimal by 
default (the period is optional). To specify an octal number, 
place a pound sign (#) in front of the number. If there are any 
conflicts, BRU issues a warning message. 

When you do not use the /POSITION qualifier, BRU places the index 
file in the same location as that on the input volume. 

/PROTECTION: SYSTEM:value 
OWNER:value 
GROUP: value 
WORLD: value 

Specifies the default protection status for all files created on 
the output volume being initialized. This protection value does 
not apply to files being transferred by BRU, but rather to 
subsequent files created on the output volume by an ACP when the 
volume is mounted. If you do not specify any values, they 
default to the protection values of the input disk. 

The protection value can be R(ead), W(rite), E(xtend), or 
D(elete), or any combination of the four. See the RSX-11M/M-PLUS 
MCR Operations Manual for an explanation of file protection . 
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/REVISED: BEFORE: (dd-mmm-yy hh:mm:ss) 
BEFORE : dd-mmm-yy 
BEFORE :hh :mm:ss 
AFTER: (dd-mmm-yy hh:mm:ss) 
AFTER :dd-mmm-yy 
AFTER :hh :mm:ss 



Backs up or restores files revised or created on, before, or 
after the specified date and time. 

If you use the BEFORE option, BRU copies any files revised or 
created at or before the specified date and/or time. 

If you use the AFTER option, BRU copies any files revised or 
created on or after the specified date and/or at or after the 
specified time. 

As with the /CREATED qualifier, if you specify both a date and 
time, the date and time must be enclosed in parentheses. If you 
specify only a date or time, the parentheses are not necessary. 
If you specify only a time, BRU uses the current date as a 
default. If you specify only a date, the time defaults to 00:00. 



/REWIND 



Rewinds the first magnetic tape of a tape set before executing a 
backup or restore operation. 

When specified with an input tape, BRU rewinds the first tape of 
the tape set before searching for a backup set. 

When specified with the /APPEND qualifier, BRU rewinds the output 
tape and then searches for the logical end-of-tape before 
executing the backup operation. 



/SUPERSEDE 



Specifies that when file specifications on the mounted output 
volume are identical to file specifications on the input volume, 
the file on the output volume is deleted and replaced with the 
file from the input volume. 

For an /IMAGE operation, if you create a backup set file on a 
mounted volume and a file with the same name exists, /SUPERSEDE 
replaces this file. 



/NOSUPERSEDE is the default. 



/TAP E_L ABEL : label 

Specifies the 6-character volume identifier on the American 
National Standard (ANS) X. 327-1978 label to be placed on a tape 
during a backup operation or to be compared with the label on the 
tape for append and restore operations. This allows you to check 
that you are using the correct tape. 



/UFD 

Directs BRU to create UFDs (if they do not already exist) on a 
mounted output volume, then copy into it the files from the same 
UFD on the input volume. If you do not specify /UFD, BRU does 
not copy the files. /UFD is used only with the /NOINITIALIZE 
qual i f ier . 
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/VERIFY 

Copies data from the input volume, performs a compare operation 
between the input volume and the output volume after the 
transfer, and reports any differences. 

/WINDOWS: number 

Specifies the default number of mapping pointers to be allocated 
for file windows when initializing an output disk. This value is 
used by an ACP when the volume is mounted. A file window 
consists of a number of pointers and is stored in memory when the 
file is opened. The default number of mapping pointers is the 
same as for the input disk. 

Choosing a large number of mapping pointers may speed up file 
access. However, a large file window also uses up system dynamic 
memory (pool space) . If pool space is more critical than file 
access time, choose a smaller number of pointers. 

Refer to the IAS/RSX-11 I/O Operations Reference Manual for more 
information . 



7.5 STAND-ALONE BRU 

You can also run BRU stand-alone. On RSX-11M, the stand-alone system 
is called BRU64K. On RSX-11M-PLUS , it is BRUSYS. The difference 
between the BRU task contained in these stand-alone systems and the 
on-line BRU described in the preceding sections is that stand-alone 
BRU does not support a restore operation to a mounted volume. 
Therefore, BRU will always initialize the output disk volume. There 
is no /INITIALIZE qualifier and the BRU task does not ask if you want 
to initialize the output volume. 

Other qualifiers that cannot be used in the stand-alone BRU systems 
are /NEW_VERSION, /NOINITIALIZE, /NOSUPERSEDE , /SUPERSEDE, and /UFD. 

Unlike other stand-alone systems, the BRU systems contain other tasks 
besides the BRU task. You invoke these other tasks before invoking 
the BRU task. (One task, CNF, is first invoked automatically when you 
boot the stand-alone BRU system.) 

On RSX-11M, BRU64K contains two other tasks besides the BRU 
task — BAD and CNF. BAD is the Bad Block Locator Utility (described 
in Chapter 6) and CNF is the Stand-alone Configuration and Disk Sizing 
Program (described in this section) . You invoke BRU and BAD with the 
MCR RUN command. CNF is invoked automatically when you boot BRU64K. 
(You can use CNF again by also invoking it with the RUN command.) 

On RSX-HM-PLUS, BRUSYS contains four other tasks besides the BRU 

task. These other tasks are FMT, BAD, DSC, and CNF. FMT is the Disk 

Volume Formatter Utility (described in Chapter 5) and DSC is the Disk 

Save and Compress Utility Program (described in Chapter 8) . You 
invoke BRU , FMT, BAD, ana DSC with the MCR RUN command. As on 

RSX-11M, CNF is invoked automatically when you boot the system. (You 
can use CNF again by also invoking it with the RUN command.) 

If you need to use FMT or BAD, you must run them before running BRU. 
When you are finished with these other tasks, issue the RUN BRU 
command to begin using BRU. 
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After you boot the stand-alone BRU system, the CNF task runs 
automatically. It lists the switches available for your use and then 

prompts you for the devices you will be using. It is recommended that 

you first specify /DEV to find out the status of the devices on your 
system. For example: 

Enter first device: /DEV 

Device CSR Vector CSR Status 

DB 176700 254 Present 

DK 177404 220 Present 

DL 174400 160 Not Present 

DM 177440 210 Present 

DP 176714 300 Present 

DR 176300 150 Present 

DU 172150 154 Not Present 

MF FOR=0 175400 260 Not Present 

MM FOR=0 172440 224 Present 

MS 172522 330 Not Present 

MT 172522 320 Not Present 

Enter first device: 



You can also use CNF and its switches to set the CSR and vector 
addresses of devices present on your system or to change the default 
formatter number (F0R=n) for some of the magnetic tape devices. For 
example :: 

Enter first device: DM2 :/CSR=177450/VEC=274 
Enter second device: DL: 
The CNF switches are: 
/CSR=nnnnnn 

Changes the default CSR for the device. 

/DEV 

Lists the default CSR and vector addresses for all of the 
devices. It is recommended that you use this switch first 
to find out what devices are present on your system. 

/FOR=n 

Changes the default formatter number for some of the 

magnetic tape devices. The switch is valid for only the 

MF:- and MM:-type devices. The initial default for n is 0. 

/VEC=nnn 

Changes the default vector for the device. 



7.5.1 Locating and Booting Stand-Alone BRU 

On RSX-11M, the BRU64K system on the distribution kits requires 64K 
words of memory to run the three tasks (BRU, BAD, CNF) . The BRU64K 
system image (BRU64K . SYS) and symbol table (BRU64K . STB) are located in 
UFD [1,51] on the following disk volumes: 
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I BIG DISK KIT - RSXM35 

RK06/RK07 KIT - CLISRC 
RL01/RL02 KIT - RLUTIL 

On RSX-11M-PLUS, the BRUSYS system on the distribution kit requires 

I124K words of memory to run the five tasks {BRU, BAD, FMT, DSC, CNF) • 
The BRUSYS system image ana symbol table are located in UFD [6,54] on 
the distribution disk. The name of the disk is RSX11MPBL15 . 

On both RSX-11M and RSX-11M-PLUS , you can bootstrap the stand-alone 
BRU system in one of two ways: 

1. Software boot stand-alone BRU by using the privileged MCR 
BOOT command as follows: 

I For RSX-11M mapped systems 

>INS $BOO 

>BOO [1,51]BRU64K 

For RSX-11M-PLUS 

>INS $BOO 

>B00 [6,54]BRUSYS 

2. Hardware boot stand-alone BRU following the hardware 
bootstrap procedure for your processor. 

To create a hardware-bootable stand-alone BRU tape from the 
distribution disk, use the Virtual Monitor Console Routine 
(VMR) to save the system image to tape as follows: 

For RSX-11M 

I>SET /UIC=[1,54] 
RUN [1,54] VMR 
ENTER FILENAME: BRU64K 
VMR>SAVE MT : BRU64K 

VMR> gTRLg ) 

For RSX-11M-PLUS 

I>SET /UIC=[6,54] 
RUN VMRM41 

ENTER FILENAME: BRUSYS 
VMR>SAVE MT : BRUSYS 
VMR> £truz ) 

This tape contains a hardware-bootable image of the 
stand-alone BRU system. (See the RSX-11M/M-PLUS System 
Management Guide for information on VMR.) 



7.6 ON-LINE BRU BAD BLOCK PROCESSING 

After you have formatted a disk with the Disk Volume Formatter Utility 
(FMT; see Chapter 5) and marked any bad blocks on it with the Bad 
Block Locator Utility (BAD; see Chapter 6), you can initialize it 
with BRU. 

If you specify the /BAD qualifier with the /INITIALIZE qualifier, BRU 
uses the bad block information from running BAD on the disk to create 
the file BADBLK . SYS . This file has allocated to it all of the bad 
blocks on the disk so that other files will not try to use them. 
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The /BAD qualifier has three options: AUTOMATIC, which is the default 
option, OVERRIDE, and MANUAL . The following sections describe how to 
use these options. 



7.6.1 Using the AUTOMATIC Option 

The AUTOMATIC option specifies that BRU use the existing bad block 
information on the disk to create the file BADBLK. SYS . For last-track 
devices, BRU uses the manufacturer-written bad block information and 
the software bad sector file. For nonlast-track devices, BRU uses the 
bad block descriptor block. 



7.6.2 Using the OVERRIDE Option 

The OVERRIDE option applies only to last-track devices. It makes the 
disk appear to be a nonlast-track device. 

When you use OVERRIDE with BRU, ensure that the disk you are 
processing has previously been processed by the BAD utility with the 
BAD /OVR switch specified. Using the BAD /OVR switch makes last-track 
devices look like nonlast-track devices by using the last good block 
before the last track as the bad block descriptor block. /OVR 
processing includes that last track as bad data when it creates the 
bad block descriptor block. 

OVERRIDE processing for BRU assumes that the bad block descriptor 
block written by BAD exists on the disk being processed. 



7.6.3 Using the MANUAL Option 

The MANUAL option accepts the addresses of bad blocks you enter 
interactively at your terminal. It also specifies that BRU use either 
the manufacturer-written bad block information and the 
software-detected bad sector file (for last-track devices) or the bad 
block (for nonlast-track devices) descriptor block to create 
BADBLK SYS . If there is no software-written bad block information, a 
message will be displayed informing you that BAD has not processed the 
disk . 

When you specify /BAD : MANUAL , BRU issues a prompt at your terminal. 
To enter bad blocks, respond to the prompt with the starting logical 
block number, followed by a count of how many consecutive blocks are 
bad, in the following format: 

LBN [ : count [ . ] ] 

BRU interprets both the LBN and the count as decimal numbers. You can 
specify the LBN in octal, but you must specify the count in decimal. 
To specify an octal value for the LBN, precede it with a number sign 
(#) . If you do not specify count, it defaults to 1. 

If you enter a bad block that is already in the bad block file, BRU 
generates an error message. 

To get a list of the LBNs you have entered so far, type one slash (/) . 
To copy the LBNs into BADBLK. SYS, type two slashes (//) . 

When you have finished entering bad blocks, press the RETURN key to 
return to BRU command level. 
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7.7 USING BRU TO COPY DISKS CONTAINING SYSTEM IMAGES 

When you copy a bootable system disk to a disk of the same controller 
type, BRU automatically produces a bootable output disk for you. 

If, however, you are copying an unsaved (virgin) system or copying a 
saved system to a smaller disk or to a disk of a different controller 
tyP e / Y ou can use the procedures described in the following sections 
to ensure that BRU produces a bootable output disk. 



7.7.1 Copying an Unsaved (Virgin) System 

In an unsaved system, installed tasks are pointed to by the physical 
LBN of the task image on the disk. When you copy an unsaved system 
with BRU, BRU assigns new LBNs for the task images on the output disk. 
Therefore, if you want to be able to software boot the copied system, 
you must first use VMR to remove and reinstall any tasks. (VMR, the 
Virtual Monitor Console Routine, is described in the RSX-11M/M-PLUS 
System Management Guide . ) 



7.7.2 Copying a Saved System 

In a saved system, installed tasks are pointed to by the file-ID of 
the task image on the disk. To copy a saved system to a smaller disk 
or to a disk of a different controller type, use the following 
procedures . 



7.7.2.1 Copying to a Smaller Disk - If you want to copy a disk with a 
saved system to a smaller disk, the most common method is to first use 
the /MAXIMUM and /HEADERS qualifiers (described in Section 7.4) to 
decrease the size of the index file. BRU is then unable to preserve 
the file-IDs of the files, so you must use VMR to remove and reinstall 
any tasks in the copied system image (the image on the output disk) . 



7.7.2.2 Copying to a Different Controller Type - If you have used BRU 
to copy a hardware-bootable disk to a disk of a different controller 
type and you want the output disk to also be hardware-bootable, you 
must use the MCR BOOT command to boot the saved system on the output 
disk. Then you use the MCR SAVE /WB command to write the correct boot 
block on the output disk. 

On an RSX-I1M-PLUS system, you can copy a DB:- f DM:-, DU:-, EM:- or 
DR:-type disk to any other of these controller types without having to 
re-SAVE the system because the boot block for these devices is common 
on RSX-11M-PLUS. Use the following command to write the correct boot 
block on the output disk: 

MCR SAV /WB 



7.8 BRU FILE TREATMENT 

The following sections describe how BRU treats file dates, file 
headers, file synonyms, and lost files. 
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7.8.1 Creation and Revision Dates of Piles 

BRU always preserves the creation and revision dates of files that it 
transfers. However, since BRU creates UFDs during a restore operation 
to a disk being initialized, and also when the /UFD qualifier is 
specified, the creation date of the UFD is the date on which BRU 
created it. 



7.8.2 File Headers 

BRU preserves all characteristics of a file, if possible. There are 
three exceptions: 

• If there is insufficient room on the output volume to restore 
the file contiguously, it is restored noncont iguously . 

• The file name is updated on the file's header to match the UFD 
entry. 

• The physical end-of-file in the user attribute area is updated 
to correctly reflect the file's size. 



7.8.3 File Synonyms 

File synonyms are files that have different names but share the same 
file-ID and data. They can be created with the PIP utility but also 
occur when a file-ID from a deleted file is reused in a UFD that BRU 
has not yet copied. If you restore files with synonyms to an 
unmounted volume and you preserve file-IDs, the file synonyms are 
restored as synonyms. However, if you do not preserve file-IDs or you 
restore to a mounted volume, file synonyms are restored as separate 
f i les . 



7.8.4 Lost Files 

A file that is not contained in any UFD is known as a lost file. BRU 
does not find lost files. To find lost files, use the File Structure 
Verification Utility (VFY) with its /LOst switch before using BRU to 
back up the disk (VFY is described in Chapter 9) . 



7 . 9 EXAMPLES 

This section gives examples of various BRU operations and command 
lines. Note that the qualifiers used in the command lines have been 
truncated to three characters. All of the BRU qualifiers are unique 
to three characters. 

Examples 1 through 6 and examples 11 and 12 also show informational 
messages that BRU returns during some operations. The remaining 
examples do not include these messages. 

The following list is a summary of the operations and command lines 
shown in the examples: 

1. Disk-to-tape backup (with verification) and tape-to-disk 
restore operations. 
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2. Disk-to-disk backup operation. 

3. Disk-to-disk backup operation including changing the maximum 
number of files and initial header allocation for the output 
disk. 

4. Disk-to-disk multivolume backup operation. 

5. Disk-to-disk multivolume restore operation. 

6. Disk-to-disk multivolume backup (with appending) and disk to 
disk restore operation. 

7. Disk-to-tape incremental backup operation (by date) with tape 
ver i f icat ion . 

8. Disk-to-tape selective backup operation (by file 
specification) . 

9. Mounted disk-to-tape backup and tape-to-mounted disk restore 
operations . 

10. Disk-to-tape backup (with appending) and tape-to-mounted disk 
restore operations. 

11. Exclusion of certain files during a backup operation. 

12. Manually entering bad blocks and displaying them. 

13. Continuation command lines on RSX-11M and RSX-11M-PLUS. 

14. Continuation command lines on RSX-11M-PLUS only. 

Example 1 shows how to use BRU to back up an entire disk volume onto 
two 1600 bpi magnetic tapes and then how to restore the disk. For the 
backup operation, BRU verifies the output volumes as part of the 
operation. (Verifying volumes is specified with the /VERIFY 
qualifier.) If files do not verify, BRU returns an error message. 

To back up DM2: onto the magnetic tapes on MMO : and MM1:, use 
the following command line: 

BRU>/DEN: 1600/VER DM2: MMO : , MM1 : (RET) 
BRU - STARTING TAPE 1 ON MMO: 

BRU - END OF TAPE 1 ON MMO: 

BRU - STARTING VERIFY PASS TAPE 1 ON MMO: 

BRU - END OF TAPE 1 ON MMO: 

BRU - STARTING TAPE 2 ON MM1 : 

BRU - END OF TAPE 2 ON MMl: 

BRU - STARTING VERIFY PASS TAPE 2 ON MMl: 

BRU - END OF TAPE 2 ON MMl: 

BRU - COMPLETED 

BRU> £trl7z) 
> 
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To restore the entire disk and rewind the first input tape, use 
the following command line (the /INI qualifier specifies that 
DM2: will be initialized before the restore operation begins) : 

BRU>/REW/DEN: 1600/INI MM: , MM1 : DM2:© 

BRU - STARTING TAPE 1 ON MMO : 

BRU — * WARNING* — THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM 

BRU - END OF TAPE 1 ON MMO: 

BRU - STARTING TAPE 2 ON MM1 : 

BRU - END OF TAPE 2 ON MM1: 

BRU - COMPLETED 

BRU>gBk/lD 
> 



Example 2 shows how to do a disk-to-disk backup operation for an 
entire disk. The characteristics of the output disk default to those 
of the input disk. This operation (and every other BRU operation) can 
be done in two ways. 

>BRU/INI DM: DM1 : (RET) 
BRU - COMPLETED 

or 

> BRU (RET) 
BRU> © 
FROM: DM:© 
TO: DM1:© 

INITIALIZE OUTPUT DISK [Y/N]:Y© 
BRU - COMPLETED 

BRU>€DyD 

Th€»se two command lines tell BRU to initialize the output disk 
(DM1:) and then back up all of the files on the input disk (DM0:) 
onto it. 



Example 3 shows another disk-to-disk backup operation. This time, the 
maximum number of files and initial file header allocation for the 
output disk are changed. This information is contained in the index 
file, which can be placed at different locations on the disk. 

BRU>/INI/MAX:10000/HEA:5000/POS:BEG DM: DM1:© 
BRU - COMPLETED 

This command initializes the output disk (DM1:) and tells BRU 
that the maximum number of files allowed on the disk will be 
10000(10) and the initial file header allocation will be 5000(10) 
headers. The index file, which contains this information, will 
be placed at the beginning of the disk. When the output disk has 
been initialized, all of the files on the input disk (DM:) will 
be copied onto it. 
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Example 4 shows a multiple disk-to-disk backup operation. You must 
use the SAVE option with the /IMAGE qualifier when doing a multiple 
disk-to-disk backup operation. 

BRU>/INI/IMA:SAV/VER/MOU DL : DY : (HD 

BRU - MOUNT DISK 1 ON DYO : . PRESS "RETURN" WHEN DONE 

BRU - STARTING DISK 1 ON DYO: 

BRU - END OF DISK 1 ON DYO: 

BRU - STARTING VERIFY PASS DISK 1 ON DYO: 

BRU - END OF DISK 1 ON DYO: 

BRU - MOUNT DISK 2 ON DYO: . PRESS "RETURN" WHEN DONE 

BRU - STARTING DISK 2 ON DYO: 

BRU - END OF DISK 2 ON DYO: 

BRU - STARTING VERIFY PASS DISK 2 ON DYO: 

BRU - END OF DISK 2 ON DYO: 

BRU - MOUNT DISK 3 ON DYO: . PRESS "RETURN" WHEN DONE 

BRU - STARTING DISK 3 ON DYO: 

BRU - END OF DISK 3 ON DYO: 

BRU - STARTING VERIFY PASS DISK 3 ON DYO: 

BRU - END OF DISK 3 ON DYO: 

BRU - COMPLETED 

BRU>EIlz) 

Example 5 shows a multiple disk-to-disk restore operation. You must 
specify the RESTORE option on the command line with the /IMAGE 
qual i f ier . 

BRU>/INI/IMA:RES/VER DY : DL : © 



BRU - 


MOUNT DISK 1 ON DYO: . 


PRESS 


"RETURN" 


WHEN DONE 


BRU - 


STARTING DISK 1 ON DYO 








BRU - 


THIS DISK WILL NOT CONTAIN A 


HARDWARE 


BOOTABLE SYSTEM 


BRU - 


END OF DISK 1 ON DYO: 








BRU - 


MOUNT DISK 2 ON DYO: . 


PRESS 


"RETURN" 


WHEN DONE 


BRU - 


STARTING DISK 2 ON DYO 








BRU - 


END OF DISK 2 ON DYO: 








BRU - 


MOUNT DISK 3 ON DYO: . 


PRESS 


"RETURN" 


WHEN DONE 
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BRU 




STARTING DISK 3 ON DYO : 






BRU 




END OF DISK 3 ON DYO: 






BRU 




MOUNT DISK 1 ON DYO: . PRESS "RETURN" 


WHEN 


DONE 


BRU 




STARTING VERIFY PASS DISK 1 ON DYO: 






BRU 




END OF DISK 1 ON DYO: 






BRU 




MOUNT DISK 2 ON DYO: . PRESS "RETURN" 


WHEN 


DONE 


BRU 




STARTING VERIFY PASS DISK 2 ON DYO: 






BRU 




END OF DISK 2 ON DYO: 






BRU 




MOUNT DISK 3 ON DYO: . PRESS "RETURN" 


WHEN 


DONE 


BRU 




STARTING VERIFY PASS DISK 3 ON DYO: 






BRU 




END OF DISK 3 ON DYO: 






BRU 




COMPLETED 






BRUXEtrPz) 







Example 6 show how to append backup sets on a multivolume disk, plus 
restore the multivolume disk set. If your multivolume backup disk 
contains a backup set that does not occupy the entire disk, you can 
append backup sets on the same disk using the /APPEND qualifier. 

BRU>/APP/IMA : SAVE/BACKUP : SECOND/INI 

FROM : DB: (fH) 

TO: DK: ,DK1 : © 

BRU - MOUNT DISK 1 on DKO : . PRESS "RETURN" WHEN DONE. 
BRU - STARTING DISK 1 on DKO: 
BRU - END OF DISK 1 on DKO: 

BRU - MOUNT DISK 2 ON DK1 : . PRESS "RETURN" WHEN DONE. 
BRU - STARTING DISK 2 ON DKl : 
BRU - END OF DISK 2 ON DKl: 
BRU - COMPLETED 

BRU>( 5trl/z1 

To restore the appended backup set from the multivolume disk set, 
you have to specify the following: 

BRU>/IMA:RES/BACKUPSET:SECOND/INI DK : , DKl : DBO: 

BRU - MOUNT DISK 1 ON DKO: . PRESS "RETURN" WHEN DONE. 

BRU - STARTING DISK 1 ON DKO: 

BRU - END OF DISK 1 ON DKO: 

BRU - MOUNT DISK 2 ON DKO: . PRESS "RETURN" WHEN DONE. 
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BRU 



STARTING DISK 2 ON DKl: 



BRU 



END OF DISK 2 ON DKl: 



BRU 



COMPLETED 



BRU> gTRL/g 



Examples 7 and 8 show how to do incremental backups with BRU. Example 
7 (following) shows a backup-by-date operation (and tape verification) 
and Example 8 shows a backup-by-file-specification operation. 

BRU>/RE V : AFT : (14-FEB-83 17:00) /VER (RET) 

FROM: DM: (RET) 

TO: MT:© 

This command line backs up all files on the disk that were 
revised after 5:00 P.M. on February 24, 1981. After all the 
files have been copied onto the tape, BRU verifies the tape. If 
files on the tape do not verify, BRU returns an error message. 



Example 8 shows a backup-by-file-specification operation: 

BRU>DB : [7,10] , [301,304] * .MAC,* . CMD(RET) 
TO : MM : (§ET) 

In this case, BRU backs up all the files in UFD [7,10] and all 
the .MAC and . CMD files in UFD [301,304] on the input disk to a 
magnetic tape. 



Example 9 shows how to back up files from a mounted disk and then two 
ways to restore files to a mounted disk. 

BRU>/MOU DB: [304,303] , [7,326] MM: (RET) 

This command line informs BRU that the input disk is mounted as a 
Files-11 device. 

BRU>/NOI MM: [304,303] DB : (RET) 

This command line restores the files in UFD [304,303] on the 
magnetic tape to the mounted disk volume without first 
initializing it. In this case, any file on the tape that is 
identical to a file already on the disk is not superseded (the 
input file is not copied) . Not superseding files is the default 
operation for BRU. 

BRU>/NOI/NEW MM: [7,326] DB:© 

This command line restores the files in UFD [7,326] on the 
magnetic tape to the mounted disk volume without first 
initializing it. The /NEW (/NEW VERSION) qualifier tells BRU to 
create a new version of any duplTcate files. 



Example 10 shows how to append files from a disk to a tape with a 
backup set already on it and then how to restore the set back to a 
mounted disk. 
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BRU> /APP/VER/BAC : TODAY © 
FROM: DB: [7,326] © 
TO: MM:© 

This command line appends the files in UFD [7,326] on the input 
disk to a magnetic tape. The name of the backup set being 
written on the tape is "TODAY". After the backup operation is 
completed, BRU verifies the tape. 

BRU>/REW/BAC: TODAY/NO I MM: DB : ©) 

This command line rewinds the magnetic tape containing the backup 
set "TODAY". All of the files in TODAY are then copied back onto 
a mounted output disk. If a file already exists on the disk, BRU 
defaults to /NOSUPERSEDE to resolve the conflict. 



Example 11 shows how to exclude certain files from being copied during 
a backup operation. 

BRU>/MOU/EXC DM: [1,6] MMl:© 
BRU - STARTING TAPE 1 ON MM1 : 

BRU - END OF TAPE 1 ON MMl : 

BRU - COMPLETED 

BRU> Strl/z) 

This command line backs up all of the files on the input disk, 
except for those in UFD [1,6] , onto the magnetic tape. 



Example 12 shows how to enter bad blocks manually and how to display 
them. 

BRU>/REW/ IN I/BAD: MAN MMl: DM:© 
BRU - STARTING TAPE 1 ON MMl: 

BRU>LBN(S) =/© 

053768:022 
BRU>LBN(S)=10500:2 
BRU>LBN(S) =12000 
BRU>LBN(S)=/© 

053768:022 

010500:002 

012000:001 
BRU>LBN(S) =//© 

BRU — *WARNING* — THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM 
BRU - END OF TAPE 1 ON MMl: 
BRU - COMPLETED 
BRU> I 5TRL/Z) 

This command line first initializes the output disk and then 
requests you to enter the locations of any bad blocks before 
copying the files from the magnetic tape. The first slash (/) 
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displays the bad blocks in the bad sector file on the last track 
of the disk. The second slash displays those blocks and the ones 
that have been entered manually. Two slashes (//) returns you to 
the BRU command level . 

In this example, two locations of bad blocks for the disk were 
entered: there are 2 bad blocks starting at LBN 10500 and 1 
block at LBN 12000. You can enter the LBN in either decimal (the 
default) or octal (precede the number with #) , but the number of 
bad blocks must be in decimal. When you do not specify the 
number of bad blocks, it defaults to 1. 



Examples 13 and 14 show BRU continuation command lines on RSX-11M and 
RSX-11M-PLUS (see Section 7.2.2.2 for more information). 

RSX-11M and RSX-11M-PLUS 

>RUN BRU 

BRU>/REWIND- 

BRU>/INVOLUME:BACKUP- 

BRU>/BACKUP_SET: 25MAY81- 

BRU> /TAPE_LABEL : BRU123 

FROM: DM0: 

TO: MM0: 

RSX-11M and RSX-11M-PLUS support continuation lines when you 
invoke BRU and then respond to the BRU> prompt. The command line 
can be 256(10) characters long. 

RSX-llM-PLUS only (for command lines no longer than 80 
characters) 

> BRU/REWIND- 

->/INVOLUME:BACKUP- 

->/BACKUP_SET: 25MAY81- 

-> /TAPE_LABEL : BRU123 DM0: MM0 : 

RSX-llM-PLUS also supports continuation lines when you use BRU 
from \thm MCR comatand level . In this case, the command line can 
only be 80 characters long (including the initial line) • 



7.10 MESSAGES 

This section lists BRU information and error messages, describes the 
meaning of the message, and suggests actions to correct the errors. A 
WARNING message indicates an error that may or may not terminate the 
BRU operation. A FATAL message indicates an error that always 
terminates the operation. 



BRU — *WARNING* — ALLOCATION FAILURE [ufd] filename . type ; version 

Explanation: During a copy to a mounted volume, there was not 
enough free space to copy the specified file. 

User Action: Create enough free space on the volume by using the 
Peripheral Interchange Program (PIP; see Chapter 3) to delete or 
truncate some files and then reenter the command line. 



7-34 



BACKUP AND RESTORE UTILITY (BRU) 



BRU — * FATAL* — ALLOCATION FOR SYSTEM FILE EXCEEDS VOLUME LIMIT 

Explanation: A system file (one of the following files: 
INDEXF.SYS, BITMAP. SYS, BADBLK . SYS , 000000. DIR) requires more 
space than is available on the output disk. This will usually 
occur if the output disk is smaller than the input disk. 

User Action: Use the /POSITION qualifier to force allocation to 
start at the beginning of the disk and/or use the /MAXIMUM and 
/HEADERS qualifiers to reduce the size of INDEXF.SYS. 



BRU — * FATAL* — AMBIGUOUS OPTION 

Explanation: An option specified with a qualifier, is not unique. 
For example, the "B" in /POSITION:B could mean either BEGINNING 
or BLOCK. 

User Action: Use a form of the option that is unique. All BRU 
options are unique to two characters. 



BRU — * FATAL* — AMBIGUOUS QUALIFIER 

Explanation: A qualifier is not unique. For example, /RE could 
mean either /REVISED or /REWIND. 

User Action: Use a form of the qualifier that is unique. All 
BRU qualifiers are unique to three characters. 



BRU ~ * WARNING* — APPENDING AT DEFAULT BPI ON ddnn : 
or 

BRU — * WARNING* — APPENDING AT 1600 BPI ON ddnn: 

Explanation: The wrong tape density was specified with the 
/APPEND qualifier. BRU performs an append operation only at the 
density at which the tape was previously written. The default 
bpi in the first message is either 800 or 6250, depending on the 
type of tape drive. 

User Action: None. BRU continues at the correct density. 



BRU — * FATAL* — ATTACH FAILED ON ddnn: 

Explanation: BRU could not attach the specified device. 

User Action: Check to see if another task has the device 
attached or if the device has a volume mounted on it. 



BRU — * FATAL* — BACKUP DISK READ ERROR 

Explanation: An unrecoverable read error occurred on the output 
backup disk, possibly caused by an undetected bad block, or an 
error occurred while BRU was sizing the input or output disk for 
a multivolume backup operation. 

User Action: Use the BAD utility to locate all bad blocks. Then 
use BRU with the /BAD : AUTOMATIC qualifier to use the existing bad 
block information on the disk to create the file BADBLK. SYS. 
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BRU — * FATAL* — BACKUP DISK WRITE ERROR 

Explanation: An unrecoverable write error occurred on the output 
backup disk during a multivolume backup operation. The error 
could have been caused by an undetected bad block. 

User Action: Use the BAD utility to locate all bad blocks (see 
Chapter 6) . Then use BRU with the /BAD: AUTOMATIC qualifier to 
use the existing bad block information on the disk to create the 
file BADBLK.SYS. 



BRU — * WARNING* — BAD BLOCK DATA ERROR 

Explanation: A manually entered bad block location, count, or 
syntax was incorrect. 

User Action: Enter the correct information. 



BRU — *WARNING* — BAD BLOCK FILE FULL 

Explanation: The manual addition of bad blocks has resulted in 
more than 204(10) sets of contiguous bad blocks. 

User Action: None. You cannot enter more bad blocks than the 
file will hold. You may not want to use the disk anymore. 



BRU — *WARNING* ~ BLOCK EXCEEDS VOLUME SIZE 

Explanation: You have manually entered a bad block that is 
larger than the size of the output disk. 

User Action: Enter the correct block. 



BRU — *WARNING* — BOOT BLOCK IS BAD 

Explanation: BRU cannot write to the output boot block. 
Therefore, the output disk will not be hardware-bootable. 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — BOOT BLOCK IS CORRUPT 

Explanation: The input disk does not contain a valid boot block. 
The output disk will not be hardware-bootable. 

User Action: None. BRU continues the operation. 



BRU — * WARNING* — BOOT BLOCK READ ERROR 

Explanation: An error occurred while BRU was reading the boot 
block . 

User Action: None. BRU continues the operation. 
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BRU — * WARNING* — BOOT BLOCK VERIFY ERROR ON ddnn: 

Explanation: During a backup operation, the boot block on the 
output device did not match the boot block on the input device. 

User Action: None. BRU continues the operation. 



BRU— * FATAL* — CANNOT APPEND ON A MOUNTED DISK 

Explanation: A multivolume backup operation to disk is not 
possible because you cannot append to a mounted disk. You can 
only use the /APPEND qualifier when doing a multivolume disk 
backup operation to an unmounted disk. 

User Action: You must use another disk to proceed with your 
backup operations. 



BRU — * FATAL* — CANNOT MIX DIFFERENT TYPES OF DISKS 

Explanation: The input disk and the output disk are of different 
types for a multivolume disk operation. 

US€»r Action: You must specify the same type of disk for the 
input and/or output disk when you do a multivolume restore or 
backup operation. 



BRU— *WARNING* ~ CANNOT RESTORE CONTIGUOUSLY [uf d ] f i lename . type ; vers i on 

Explanation: The output device does not contain enough 
contiguous blocks to restore the indicated contiguous file. The 
file will be restored noncontiguously . 

Useir Action: You can use the Peripheral Interchange Program 
(PIP; see Chapter 3) to make the file contiguous again. Use the 
PIP switches /DE and /TR to reclaim disk space by deletion or 
truncation . 



BRU — * WARNING* — CLOSE OR WRITE ATTRIBUTES ERROR [ufd ] f i lename . type ; vers ion 
I/O ERROR CODE number 

Explanation: During a copy to a mounted volume, BRU encountered 
an error while attempting to close the specified file. 

User Action: If possible, determine the cause of the error from 
the I/O code. (Refer to the IAS/RSX-11 I/O Operations Reference 
Manual . ) If it is correctable, delete the portion of the file 
that BRU has copied, and reenter the command line. 



BRU — COMPLETED 

Explanation: The BRU operation is complete. 

User Action: Enter another BRU command line or exit with a 
CTRL/Z. 
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BRU — *FATAL* — CONFLICTING QUALIFIERS 

Explanation: Two or more of the specified qualifiers are 
mutually exclusive: for example, /SUPERSEDE and /NOSUPERSEDE . 

User Action: Reenter the command line. 



BRU — *WARNING* — DATA ID RECORD VERIFY ERROR 

Explanation: An error occurred while BRU was verifying an 
80-byte data-ID record. 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — DATA RECORD VERIFY ERROR [ ufd ] f i lename . type ; vers i on 
FILE ID number LBN number 

Explanation: There was a difference in a data block on input and 
output devices. The file-ID of the file with the error and the 
LBN of the block follow the message. 

If a UFD is printed with a file name, the UFD is the owner UFD 
from the file's header, not the UFD in which the file is 
contained . 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — DATA WAS LOST DUE TO 10 ERRORS [ufd] fi lename . type; version 

Explanation: A tape read error resulted in missed data. The 
files are restored, but may contain erroneous data. 

If a UFD is printed with a file name, the UFD is the owner UFD 
from the file's header, not the UFD in which the file is 
contained . 

User Action: None. BRU continues the operation. 



BRU — * FATAL* — DEVICE CONFLICT 

Explanation: Both a tape and a disk drive were specified as part 
of the input or output device specification. 

User Action: The device must be either a disk or a tape, but not 
both. This applies to both input and output specifications. 



BRU ~ * FATAL* — DEVICE NOT IN SYSTEM 

Explanation: A device was specified that does not exist in the 
system. 

User Action: Reenter the command line, specifying the correct 
device specification. 
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BRU — * FATAL* — DEVICE NOT SUPPORTED 

Explanation: The specified device was not a tape or a disk, or 
it was a disk that is not supported by BRU. 

User Action: BRU supports only certain disk and magnetic tape 
devices. See Table 7-2 for a list of supported devices. Reenter 
th€» command line, specifying supported devices. 



BRU — * FATAL* — DIRECTIVE ERROR 

Explanation: An internal error occurred in BRU. 

Uscsr Action: Reenter the command line. If the error persists, 
submit a Software Performance Report (SPR) that includes a hard 
copy of the BRU operations and error messages. 



BRU — *WARNING* — DIRECTORY VERIFY ERROR 

Explanation: A directory record on the input device did not 
match a directory record on the output device. 

User Action: None. BRU continues the operation. 



BRU — * FATAL* — DISK IS AN ALIGNMENT CARTRIDGE 

Explanation: The last track identified the disk as an alignment 
cartridge, which cannot be initialized as a Files-11 volume. 

User Action: Reenter the command line, using a different output 
volume . 



BRU — * — DISK LABEL ERROR 

Explanation: An I/O error occurred while BRU was reading or 
writing a disk label. A write error is fatal; a read error is 
not fatal as long as BRU can continue reading the disk. See the 
IAS/RSX-11 I/O Operations Reference Manual for the definition of 
thi I/O error code number. 

User Action: If a write error occurred, reenter the command 
line, specifying a different disk. 



BRU — * WARNING* — DISK OUT OF SEQUENCE. PLEASE MOUNT CORRECT DISK. 

Explanation: The wrong disk volume was mounted on the disk drive 
during a restore-f rom-disk operation from a multivolume backup 
set . 

User Action: Mount the correct disk on the drive. 
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BRU — * FATAL* — DISK READ ERROR 

Explanation: An unrecoverable read error occurred on the output 
disk, possibly caused by an undetected bad block, or an error 
occurred while BRU was sizing the input or output disk. 

User Action: Use the BAD utility to locate all bad blocks. Then 
use BRU with the /BAD: AUTOMATIC qualifier to use the existing bad 
block information on the disk to create the file BADBLK . SYS . 



BRU — * FATAL* — DISK WRITE ERROR 

Explanation: An unrecoverable write error occurred on the output 
disk. The error could have been caused by an undetected bad 
block . 

User Action: Use the BAD utility to locate all bad blocks (see 
Chapter 6) . Then use BRU with the /BAD: AUTOMATIC qualifier to 
use the existing bad block information on the disk to create the 
file BADBLK. SYS. 



BRU — * FATAL* — DOUBLY DEFINED QUALIFIER 

Explanation: The same qualifier was specified more than once on 
the command line. 

User Action: Reenter the command line, specifying the qualifier 
once . 

BRU — *WARNING* — DUPLICATE BLOCKS FOUND 

Explanation: A manually entered bad block was already in the bad 
block file. 

User Action: None. BRU continues the operation. 

BRU — END OF DISK Number ON ddnn: 

Explanation: BRU has finished transferring data or verifying a 
disk . 

User Action: None. This is an informational message. 

BRU — END OF TAPE number ON ddnn: 

Explanation: BRU has finished transferring data or verifying a 
tape . 

User Action: None. This is an informational message. 



BRU — * FATAL* — END OF VOLUME ENCOUNTERED. BACKUP SET NOT FOUND 

Explanation: The backup set specified for a restore operation is 
not on the tape or disk volume. 

User Action: Mount the correct tape or disk volume or reenter 
the command line, specifying the correct backup set name. 
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BRU — *WARNING* — EOT MARKER ERROR 

Explanation: During a backup operation, an error occurred while 
BRU was writing or verifying the end-of-tape label on the output 
tape . 

After a restore operation, an error occurred while BRU was 
positioning the tape at the end of a backup set for a subsequent 
operation . 

User Action: On a write error, BRU rewinds the current tape and 
places it off-line. BRU then requests that a new tape be mounted 
and rewrites the data on the new tape. 

On a verify error, BRU continues the operation. 

On a positioning error, BRU finishes the operation. If you want 
to perform another BRU operation on the tape, use the /REWIND 
qualifier to position the tape to beginning-of-tape . 



BRU — * WARNING* — ERROR ACCESSING FILE 
I/O ERROR CODE number 
FILE ID number 

Explanation: An error occurred while BRU was writing data into a 
file, or BRU tried to do a compare read on a file that was 
already opened. BRU will continue with the next file. 

See the IAS/RSX-11 I/O Operations Reference Manual for the 
definition of the I/O error code number. 

User Action: After BRU has finished, delete the file and then 
enter a command line, specifying the file. 



BRU — *WARNING* — ERROR ACCESSING UFD. SKIPPING [ufd] 
I/O ERROR CODE number 

Explanation: During a copy to a mounted volume, an error 
occurred when BRU attempted to access a directory. See the 
IAS/RSX-11 I/O Operations Reference Manual for the definition of 
the I/O error code number . 

User Action: If possible, determine the cause of the error from 
the I/O error code. If correctable, try the copy operation 
again . 



BRU — *FATAL* — ERROR LIMIT EXCEEDED 

Explanation: BRU has reached the specified number of tape read 
errors and terminated execution. 

User Action: Reenter the command line, using a different tape 
drive, or reenter the command line after cleaning the tape drive 
heads on the original drive. 



BRU — * FATAL* — ERROR READING COMMAND FILE 

Explanation: An I/O error occurred while BRU was reading the 
indirect command file. 

User Action: Reenter the command line. 
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BRU — *WARNING* — ERROR READING DATA BLOCKS 
I/O ERROR CODE number 
FILE ID number LBN number 
or 

RECOVERED 

Explanation: An I/O error occurred while BRU was reading a data 
block from the disk. The file-ID of the file that contains the 
block and the LBN of the block are displayed as well as the I/O 
error code. If RECOVERED is printed after the message, the block 
was recovered by re-reading the disk. 

See the IAS/RSX-11 I/O Operations Reference Manual for the 
definition of the I/O error code. 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — ERROR READING UFD [ufd] 

Explanation: An I/O error occurred while BRU was reading a block 
from the specified UFD. Any files contained in this block of the 
UFD are not backed up. 

User Action: Reenter the command line. If the error still 
occurs, you can find the lost files by using the VFY utility 
(refer to Chapter 9). 



BRU — *WARNING* — ERROR READING UFD HEADER [ufd] 

Explanation: An error occurred while BRU was reading the header 
of the specified UFD. Files in this UFD are not backed up. 

User Action: Reenter the command line. If the error still 
occurs, use the VFY utility to find the lost files (see Chapter 
9) . 



BRU — *WARNING* — EXTENDING INDEX FILE 

Explanation: The initial number of file headers was too small. 
Either 256(10) or 16(10) more headers will be allocated, 
depending on the number of blocks on the output disk. 

User Action: None. BRU continues the operation. 



BRU — *FATAL* — FAILED TO READ BAD BLOCK FILE 

Explanation: BRU was unable to read the bad block information 
from a last-track output disk. 

User Action: Reenter the command line, using the /BAD: OVERRIDE 
qual i f ier . 



BRU — *WARNING* — FILE HEADER READ ERROR [ ufd ] f i lename . type ; vers i on 
I/O ERROR CODE number 

Explanation: An I/O error occurred while BRU was reading a file 
header. That file is not backed up. See the IAS/RSX-11 I/O 
Operations Reference Manual for the definition of the I/O error 
code number. 

User Action: None. BRU continues the operation. 
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BRU — * WARNING* — FILE HEADER VERIFY ERROR [ ufd ] f i lename . type ; vers i on 

Explanation: The file header of the specified file on the output 
device is not the same as that on the input device. 

Os€»r Action: None. BRU continues the operation. 

BRU — * WARNING* — FILE ID AREA VERIFY ERROR 

Explanation: The BRU-generated file-ID area of a data record was 
different on the input and output devices. 

User Action: None. BRU continues the operation. 

BRU — * FATAL* — FILE ID EXCEEDS MAXIMUM NUMBER OF FILES 

Explanation: You specified a maximum number of files with the 
/MAXIMUM qualifier that was smaller than a file-ID encountered on 
the input volume. 

User Action: Reenter the command line, specifying a larger value 
with the /MAXIMUM qualifier. 

BRU — 'WARNING* — FILE ID SEQUENCE NUMBER ERROR [uf d ] fi lename . type ; ver si on 
Explanation: The two possible sources of this error are: 

1. The sequence number in the file-ID of a file does not 
match the sequence number of the file's entry in the 
UFD. 

2. The sequence number of a UFD does not match the sequence 
number of the UFD's entry in the Master File Directory 
(MFD) . 

Therefore, the file or UFD is not valid and is not copied. 
User Action: None. BRU continues the operation. 

BRU — * WARNING* — FILE IDS WILL NOT BE PRESERVED 

Explanation: File-IDs cannot be preserved because the index file 
bitmap on the output disk is too small. This is because the 
value specified with the /MAXIMUM qualifier was too { small. 

User Action: None. BRU continues the operation without 
preserving file-IDs. If your input disk had a hardware-bootable 
system on it, your output disk will not be hardware-bootable. 

If you want the disk to be hardware-bootable, perform the BRU 
operation again, specifying a larger value with the /MAXIMUM 
qualifier . 

BRU — * WARNING* — FILE MARKED FOR DELETE [uf d ] f i lename . type ; ver s ion 

Explanation: The marked-f or-delete bit (SC.MDL) of the system 
controlled characteristics in the file header was set, indicating 
that the file was partially deleted. The file is not copied. 

User Action: None. BRU continues the operation. 
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BRU — *WARNING* — FILE NOT FOUND [ ufd ] f i lename . type ; vers i on 

Explanation: During a backup operation, BRU cannot find the 
header for the specified file or directory in the index file. 
The file is not copied. 

During the verify or compare pass of a restore operation, BRU 
cannot find the specified file on the output device. 

User Action: None. BRU continues the operation. 



BRU — * FATAL* ~ FILE NOT FOUND 

Explanation: BRU could not find the specified indirect command 
file. 

User Action: Reenter the command line, correctly specifying the 
indirect command file. 



BRU — * WARNING* — FILE NOT SUPERSEDED [ufd ] f i lename . type ; vers ion 

Explanation: During a copy to a mounted volume with /NOSUPERSEDE 
specified (or defaulted) , the specified file was not restored 
because it already existed on the output disk. 

User Action: If you want the file to be restored, enter a 
command line, specifying the file and either /SUPERSEDE or 
/NEW VERSION. 



BRU — *FATAL* — HANDLER NOT RESIDENT 

Explanation: The device driver for the specified device is not 
loaded . 

User Action: Load the driver for the specified device or reenter 
the command line, specifying the correct device name. 



BRU — *WARNING* — HEADER ID RECORD VERIFY ERROR 

Explanation: The BRU-generated header-ID record on the output 
device is different from the one on the input device. 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — HEADER READ ERROR [ ufd ] fi lename . type ; vers i on 
I/O ERROR CODE number 

Explanation: An I/O error occurred while BRU was reading a file 
header in the index file during a backup operation. 

If this error occurs during a restore operation, it is fatal. 

See the IAS/RSX-11 I/O Operations Reference Manual for the 
definition of the I/O error code number. 

User Action: None. 
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BRU — * FATAL* — HOME BLOCK READ ERROR 
I/O ERROR CODE number 

Explanation: An I/O error occurred while BRU was reading the 
home block on the input device. See the IAS/RSX-11 I/O 
Operations Reference Manual for the definition of the I/O error 
code number. 

User Action: Reenter the command line. 



BRU — * WARNING* ~ HOME BLOCK VERIFY ERROR 

Explanation: The home block on the output device is different 
from the home block on the input device. 

User Action: BRU continues, but it is suggested that you retry 
the operation. 



BRU — * FATAL* — HOME BLOCK WRITE ERROR 

Explanation: An unrecoverable I/O error occurred while BRU was 
writing the home block on the output device. 

User Action: Use the BAD utility to find all the bad blocks on 
the disk before initializing it. 



BRU — * FATAL* — ILLEGAL USE OF DIRECTORY QUALIFIER 

Explanation: Possible sources for this error are: 

1. The /DIRECTORY qualifier was specified with an output 
device . 

2. The /DIRECTORY qualifier was specified with a device 
other than a tape or backup disk with the BRU container 
file. 

3. The /INITIALIZE qualifier or any of its related 
qualifiers were specified with the /DIRECTORY qualifier. 

User Action: Refer to Section 7.4 for a description of valid 
uses of the /DIRECTORY qualifier. 



BRU — * FATAL* — INCONSISTENT INITIALIZE QUALIFIERS 

Explanation: The /INITIALIZE qualifier or any of its related 
qualifiers were specified for the output disk, but the 
/NOINITIALIZE qualifier was also used. 

User Action: Reenter the command line. 



BRU — * FATAL* — INDEX FILE HEADER READ ERROR 
I/O ERROR CODE number 

Explanation: An I/O error occurred while BRU was reading the 
header of the index file on the input disk. See the IAS/RSX-11 
I/O Operations Reference Manual for the definition of the I/O 
error code number. 

User Action: Reenter the command line. 
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BRU — *FATAL* — INDEX FILE WRITE ERROR 

Explanation: An I/O error occurred while BRU was writing the 

index file on the output disk. 

User Action: Use the BAD utility (see Chapter 6) to identify the 

bad blocks on the output disk, then reenter the command line. 



BRU — *FATAL* — INDEXF.SYS IS FULL 

Explanation: The index file cannot map any more file headers. 

User Action: Reenter the command line, specifying a larger value 
with the /MAXIMUM qualifier. 



BRU — * FATAL* — INITIALIZE QUALIFIERS INVALID WHEN OUTPUT IS TAPE 

Explanation: The /INITIALIZE qualifier and the other qualifiers 
that you can specify with it may be used only when the output 
device is a disk. 

User Action: Reenter the command line. 



BRU — *FATAL* — INPUT DEVICE EQUALS OUTPUT DEVICE 

Explanation: The input and output devices must be different. 

User Action: Reenter the command line, specifying different 
devices for input and output. 



BRU — * FATAL* ~ INPUT LINE TOO LONG 

Explanation: The maximum length of a command line is 256(10) 
characters . 

User Action: Truncate qualifiers and options to shorten the 

line. Make sure the truncated forms are unique. All BRU 

qualifiers are unique to three characters; all options are 
unique to two characters. 



BRU — *WARNING* — INPUT VOLUME STRUCTURE LEVEL DIFFERS FROM OUTPUT VOLUME 

Explanation: You have initialized the output volume, specifying 
with the /MAXIMUM qualifier that the number of files allowed on 
the volume be greater than 25593. This causes the index file on 
the output volume to have more than one file header. 

User Action: None. 



BRU — *FATAL* — INTERNAL ERROR 

Explanation: BRU has detected an error within itself. This 
should not normally occur. 

User Action: Please submit a Software Performance Report (SPR) 
with a hard copy of the BRU operations and error messages. 



7-46 



BACKUP AND RESTORE UTILITY (BRU) 



BRU — * FATAL* — INVALID DATE OR TIME 

Explanation: In the command line, a date or time was specified 
incorrectly or is out of range. 

User Action: Specify the correct date or time. 



BRU — * WARNING* — INVALID DATE OR TIME [ ufd ] f i lename . type ; vers i on 

Explanation: An invalid date or time was encountered in a file 
header during an incremental backup. 

User Action: None. BRU continues the operation. The file is 
copied . 



BRU — * FATAL* — INVALID DENSITY OR TAPE FORMAT 

Explanation: You specified a density that was neither the 
default bpi (800 or 6250) nor 1600 bpi or you attempted to use 
both 7-track and 9-track tapes in a multivolume tape set. 

User Action: In the former case, reenter the command line, 
specifying the correct density. In the latter case, only use all 
7-track or all 9-track tapes for a multivolume tape set. 



BRU — * FATAL* — INVALID DISK FORMAT 

Explanation: The disk that was mounted for an /IMAGE restore 
operation is not a BRU multivolume backup disk. 

User Action: Mount the correct disk. 



BRU — * FATAL* — INVALID FILENAME 

Explanation: The name of the indirect command file is not 
syntactically correct. 

User Action: Reenter the command line. 



BRU — * WARNING* — INVALID TAPE FORMAT 

Explanation: An invalid tape record was read during a restore 
operation . 

User Action: None. The invalid record is not restored. 



BRU — * FATAL* — INVALID VALUE OR NAME 

Explanation: A value or name specified for a qualifier has 
illegal syntax or is out of range. 

User Action: Refer to Section 7.4 to determine the legal values 
for the particular qualifier. 
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BRU — * FATAL* — MANUFACTURER BAD SECTOR FILE IS CORRUPT 

Explanation: BRU was unable to read the bad block information 
from a last-track output disk. 

User Action: Reenter the command line, specifying the 
/BAD :OVERRIDE qualifier. 



BRU — * FATAL* — MFD HEADER READ ERROR 

Explanation: An I/O error occurred while BRU was reading the 
header of the Master File Directory. 

User Action: Reenter the command line. If the header still 
cannot be read, the files on the disk are lost and may be 
recovered using the VFY utility (see Chapter 9) . 



BRU — *WARNING* ~ MFD READ ERROR 

Explanation: An I/O error occurred while BRU was reading a block 
of the MFD. BRU cannot copy the UFDs in that block of the MFD. 

User Action: Reenter the command line. If the block cannot be 
read, use the VFY utility to recover the lost files. (Refer to 
Chapter 9 for information on VFY.) 



BRU — *FATAL* — MISSING COLON 

Explanation: A qualifier option that accepts a value was not 
followed by a colon. 

User Action: Reenter the command line. 



BRU — * FATAL* ~ MORE THAN 1 LEVEL OF INDIRECTION 

Explanation: BRU does not support more than one level of 
indirect command files. 

User Action: Reenter the command line. 



BRU — MOUNT DISK n ON ddnn:. PRESS "RETURN" WHEN DONE 

Explanation: This message is issued each time BRU requests a 
disk for an image backup or restore operation. 

User Action: Mount the disk specified on the drive specified and 
then press "RETURN". 



BRU ~ MOUNT TAPE n ON ddnn: 

Explanation: There is no tape on the specified drive or the tape 
is not at load point. This message prints every two minutes 
until the tape is mounted. 

User Action: Mount the tape specified on the drive specified. 
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BRU — MOUNT ANOTHER DISK 

Explanation: BRU is requesting that a new disk be mounted after 
encountering a fatal disk write error. 

User Action: Mount a new disk on the drive. 



BRU — MOUNT ANOTHER TAPE 

Explanation: BRU is requesting that a new tape be mounted after 
encountering a fatal tape write error. 

User Action: Mount a new tape on the drive. 



BRU — *FATAL* — NAME EXCEEDS MAXIMUM ALLOWED LENGTH 

Explanation: A name, such as a backup set name, is longer than 
12(10) characters. An exception to this rule is during an /IMAGE 
backup operation to a mounted disk. You may specify more than 
12(10) characters if you are adding the name of the backup_set 
filename to the command line. For additional information, see 
Section 7.4 for a description of the /BACKUP_SET qualifier. 

User Action: Specify a name not greater than 12 characters. 



BRU — * WARNING* — NO BAD BLOCK DATA FILE FOUND 

Explanation: The BAD utility has not been run on the output disk 
to produce a file of the disk's bad blocks. 

User Action: None. BRU continues the operation. Refer to 
Section 7.6 for information on bad block processing by BRU. 



BRU — * WARNING* — NO FILES FOUND 

Explanation: During a backup or restore operation, BRU did not 
find any files to transfer. 

Use»r Action: None. 



BRU — *WARNING* — NONFATAL QUALIFIER CONFLICTS BEING IGNORED 

Explanation: You entered a qualifier that conflicts with the 
rest of the command line, but is not fatal if ignored. For 
excimple, you used the /REWIND qualifier on a disk-to-disk 
operation . 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — NO SUCH UFD EXISTS. SKIPPING [ufd] 

Explanation: During a copy to a mounted volume, BRU encountered 
one or more files in the specified UFD on the input volume, but 
there is no corresponding UFD on the output volume. 

User Action: Reenter the command line, specifying the /UFD 
qualifier to create the UFD. 
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BRU — * FATAL* — NUMBER OF HEADERS INCONSISTENT WITH MAXIMUM FILES 

Explanation: During an attempt to initialize an output volume, 
BRU found that the maximum number of files specified with the 
/MAXIMUM qualifier was inconsistent with the number of headers 
initially allocated to the index file with the /HEADERS 
qualifier . 

User Action: See the RSX-11M/M-PLUS MCR Operations Manual (the 
INI command) for the legal ranges of values for the /MAXIMUM and 
/HEADERS qualifiers. 



BRU — *WARNING* — OPEN ERROR 
I/O ERROR CODE number 

FILE I/D number or [ufd] filename. type;version 

Explanation: During a copy operation to a mounted volume, an 
error occurred while BRU was attempting to open the specified 
file. See the IAS/RSX-11 I/O Operations Reference Manual for the 
definition of the I/O error code number. 

User Action: Determine the cause of the error from the I/O error 
code. If correctable, delete any portion of the file already 
copied by BRU, then reenter the command line. 



BRU — *FATAL* — OUTPUT DISK TOO FRAGMENTED TO RESTORE 

Explanation: The internal tables in BRU have overflowed due to 
the extreme fragmentation of the output disk. If the output disk 
was initialized, then it has an unacceptable number of bad blocks 
and should not be used as a backup medium. 

User Action: Use a new disk as the output device. 



BRU — *FATAL* — OUTPUT DEVICE IS FULL 

Explanation: There are no free blocks on the output disk. This 
can occur when the output disk is smaller than the input disk or 
during an append to a tape that is already full. 

User Action: If the output disk is too small, reenter the 

command line, specifying only the files you want. If you were 

doing an append to a tape that is already full, reenter the 
command line, specifying a new tape. 



BRU — * FATAL* — OVERRIDE INVALID WITH NON LAST TRACK DEVICE 

Explanation: The OVERRIDE option may be used only when the 
output disk is a last-track device. 

User Action: Refer to Section 7.4. 



BRU — PLEASE ANSWER YES OR NO 

Explanation: BRU requires a YES or NO response. 
User Action: Enter YES or NO at your terminal. 
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BRU — * WARNING* — PRIVILEGE VIOLATION [ ufd ] f i lename . type ; vers ion 

Explanation: During a backup operation, you attempted to copy a 
file that you do not have read access to. 

Dser Action: None. BRU does not copy the file. 



BRU — * FATAL* — PRIVILEGE VIOLATION 

Explanation: The mount status of one of the devices is 
inconsistent with the qualifiers specified in the command line. 

User Action: See Table 7-1 for the correct combinations of 
mounted devices and qualifiers, then reenter the command line. 



BRU — *FATAL* — RAN OUT OF SPARE FILE IDS 

Explanation: The output disk required more file headers than the 
input disk, but no free headers were available. The lack of 
headers is probably due to one of the following reasons: 

1. The output disk is too fragmented because of bad blocks. 

2. There are no free file headers on the input disk. 

User Action: If you do not need to preserve file-IDs, reenter 
the command line, specifying the /NOPRESERVE qualifier. 

If you want to preserve file-IDs, do one of the following: 

1. If the output disk is too fragmented, run BAD (see 
Chapter 6) on it to display the number of bad blocks. 
If it contains a large number of bad blocks, you may 
want to use a different disk. 

2. Use the PIP /FR switch (see Chapter 3) to display the 
number of free file headers on the input disk. If there 
are fewer than 4 free headers, delete some of the files 
and then reenter the command line. If you still do not 
have enough file headers, specify the /NOPRESERVE 
qualifier in the command line. 



BRU — *WARNING* — RECORD NOT EXPECTED SIZE 

Explanation: The record read on the output device during a 
verify or compare operation was not the expected size. 

User Action: None. BRU continues the operation. 



BRU — * FATAL* — REQUIRED INPUT DEVICE MISSING 

Explanation: The input device was not specified on the command 
line or in response to the prompt. 

User Action: Reenter the command line. 
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BRU -- * FATAL* ~ REQUIRED OUTPUT DEVICE MISSING 

Explanation: The output device was not specified on the command 
line or in response to the prompt. 

User Action: Reenter the command line. 

BRU — REWIND ERROR ON ddnn: 

Explanation: An I/O error occurred during a tape rewind. This 

error is fatal if it occurs on the first tape of a tape set or 

during a rewind for a verify operation. The error is not fatal 
if BRU is rewinding a tape it is finished with. 

User Action: If the error is fatal, reenter the command line. 
If the error is not fatal, no action is required. 

BRU — * FATAL* — SEARCH FOR HOME BLOCK FAILED 

Explanation: The home block could not be found on the input 
disk. Either the home block is bad or the disk is not in 
Files-11 format. 

User Action: Check to see that you have the correct disk. 

BRU — STARTING TAPE n ON ddnn: 

Explanation: This message tells you which tape is being copied 
to or from which drive. 

User Action: None. This is an informational message. 

BRU — STARTING VERIFY PASS 

Explanation: This message tells you that the verify pass of a 
disk-to-disk operation is beginning. 

User Action: None. This is an informational message. 

BRU — STARTING VERIFY PASS TAPE n ON ddnn: 

Explanation: This message tells you which tape is being verified 
during a backup or restore operation. 

User Action: None. This is an informational message. 

BRU — * FATAL* — SYNTAX ERROR 

Explanation: The command line is invalid. 
User Action: Reenter the command line. 
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BRU — TAPE LABEL ERROR ON ddnn: 
I/O ERROR CODE number 

Explanation: An I/O error occurred while BRU was reading or 
writing a tape label. A write error is fatal; a read error is 
not fatal as long as BRU can continue reading the tape. See the 
IAS/RSX-11 I/O Operations Reference Manual for the definition of 
the I/O error code number. 

User Action: If a write error occurred, reenter the command 
line, specifying a different tape. 



BRU — * WARNING* — TAPE LABEL VERIFY ERROR 

Explanation: BRU detected an error in the tape label of the 
input or output tape volume during a verify operation. 

User Action: None. BRU continues the operation. 



BRU — *WARNING* — TAPE NOT AT BOT . NO REWIND OR APPEND SPECIFIED 

Explanation: For a backup operation to tape, BRU will not 
process a tape that is not at BOT unless the /APPEND qualifier 
was specified. 

User Action: If you want to start writing at the beginning of 
the tape, use the /REWIND qualifier. 

You can append to a tape only at the end of the last backup set 
on it. If the tape is already positioned there, specify /APPEND 
in the command line. If it is not, specify both /REWIND and 
/APPEND in the command line. 



BRU — *WARNING* — TAPE OUT OF SEQUENCE. PLEASE MOUNT CORRECT TAPE 

Explanation: The wrong tape volume was mounted on the tape drive 
during a restore-f rom-tape operation. 

User Action: Mount the correct tape on the drive. 



BRU — *WARNING* — TAPE POSITIONING ERROR. BACKSPACE FAILED 

Explanation: During a backup operation, the tape was not 
positioned properly for a future append operation. 

User Action: Rewind the tape before attempting the append 
operation . 



BRU — * FATAL* — TAPE POSITIONING ERROR. NO EOV ENCOUNTERED 
I/O ERROR CODE number 

Explanation: The tape spacing operation to find the 
end-of-volume for an append operation failed. See the IAS/RSX-11 
I/O Operations Reference Manual for the definition of the I/O 
error code number. 

User Action: Reenter the command line. 
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BRU — * WARNING* — TAPE READ ERROR 

Explanation: An I/O error occurred while BRU was reading a tape. 
User Action: None. BRU continues the operation. 

BRU — * FATAL* — TAPE TO TAPE NOT SUPPORTED 

Explanation: BRU does not back up a tape to another tape. 
User Action: None. 

BRU — *WARNING* — TAPE WRITE ERROR 
I/O ERROR CODE number 

Explanation: An I/O error occurred while BRU was writing to 
tape. BRU rewinds the tape and then requests that another tape 
be mounted. See the IAS/RSX-11 I/O Operations Reference Manual 
for the definition of the I/O error code number. 

User Action: If the error is related to the tape drive, 
terminate BRU and start over on another drive. 

BRU ~ THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM 

Explanation: The output disk will not be hardware-bootable. 
This can be caused by: 

1. The input disk not being bootable 

2. The system image not being copied 

3. Copying to a disk of different size or type 

NOTE 

This message is not issued when BRU is 
restoring to a mounted volume. 

User Action: None. 

BRU — *FATAL* — TOO MANY DEVICES 

Explanation: For a conventional backup a disk may be specified 
only once as an input or output device. However, up to eight 
tape drives or eight disks in an image backup may constitute the 
input or output. 

User Action: Reenter the command line, specifying only one disk 
or no more than eight tape drives. 

BRU — * FATAL* — TOO MANY FILE SPECIFICATIONS 

Explanation: More than 16(10) file specifications were specified 
on the command line. 

User Action: Reenter the command line. You can use wildcards to 
reduce the number of file specifications on the command line. 
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BRU — *FATAL* — UFD OR MFD REQUIRES UNSUPPORTED EXTENSION HEADERS 

Explanation: BRU does not support extension headers for MFDs or 
UFDs . 

User Action: This error should not occur. Please submit a 
Software Performance Report (SPR) with a hard copy of the BRU 
operations and error messages. 

BRU — *WARNING* — UFD RECORD VERIFY ERROR 

Explanation: There is a difference between input and output 
devices on a UFD record. 

User Action: None. BRU continues the operation. 

BRU — * FATAL* — UNKNOWN OPTION 

Explanation: An option was specified that was not recognized by 
BRU. 

User Action: Reenter the command line. See Table 7-3 for a list 
of legal options. 

BRU ~ *FATAL* — UNKNOWN QUALIFIER 

Explanation: A qualifier was specified that was not recognized 
by BRU. 

User Action: Reenter the command line. See Table 7-3 for a list 
of legal command qualifiers and their options. 

BRU — *FATAL* — UNSUPPORTED STRUCTURE LEVEL 

Explanation: The file structure level on the input disk is not 
supported by BRU. 

User Action: Ensure that you have the correct disk. (See the 
descriptions of the /HEADERS and /MAXIMUM qualifiers in Section 
7.4 for information on structure levels.) 



BRU — * WARNING* — VBN NOT IN FILE 

Explanation: A file-ID was encountered that is larger than the 
maximum file-ID in the index file. The file is ignored. This 
error message occurs if a UFD entry was corrupted on the input 
disk. 

User Action: None. BRU continues the operation. 



BRU — *FATAL* — VERIFY LOST 

Explanation: During the verify pass of a disk-to-tape backup 
operation, BRU has lost synchronization between the input and the 
output. This is usually caused by the tape position being lost 
or by backing up from a disk that is mounted and then changed 
during the backup operation. 

User Action: Reenter the command line. 
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BRU — -FATAL* — VOLUME NOT A BACKUP DISK 

Explanation: The disk mounted for an append or restore operation 
does not contain a backup set file generated by BRU. 

User Action: Check to see that you have the correct disk and 
reenter the command line. 



BRU — *FATAL* — VOLUME NOT A BACKUP TAPE 

Explanation: The tape mounted for an append or restore operation 
was not generated by BRU , or the tape is not positioned correctly 
for an append operation. 

User Action: Check to see that you have the correct tape, or 
reenter the command line, specifying the /REWIND qualifier to 
position the tape. 

BRU — * FATAL* — VOLUME NOT READY 

Explanation: The device is not on-line. 

User Action: Put the device on-line and reenter the command 
line . 



BRU — * FATAL* — VOLUME WRITE LOCKED 

Explanation: The output device is not wri te-enabled . 

User Action: If the output device is a tape, insert a write ring 
to make it wri te-enabled . If it is a disk, press the Write 
Enable switch on the disk drive. 



BRU — *FATAL* — WRONG BACKUP SET 

Explanation: During a restore operation from a multireel tape 
set or a multivolume disk backup set, BRU found that one of the 
tapes or disks does not contain the correct backup set. 

User Action: Reenter the command line, specifying the correct 
tape . 



BRU — * FATAL* — WRONG INPUT VOLUME LABEL 

Explanation: The input volume label specified with the /INVOLUME 
qualifier does not match the volume label of the input device. 

User Action: Reenter the command line, specifying the correct 
input volume label. 
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DISK SAVE AND COMPRESS (DSC) 



The Disk Save and Compress (DSC) utility copies a Files-11 structured 
disk either to disk or to tape and from DSC-created tape back onto 
disk. At the same time, DSC reallocates and consolidates the disk 
data storage area: it concatenates files and their extensions into 
contiguous blocks whenever possible and, therefore, reduces the number 
of retrieval pointers and file headers required for the same files on 
the new volume. 

DSC copies files that are randomly scattered over a disk volume to a 
new volume, without the intervening spaces. This eliminates unused 
space between files and reduces the time required to access them. 

A complete DSC operation is a cycle that begins with data on one disk 
and ends with the same data in compressed form on another disk. The 
operation can use one command (for a disk-to-disk cycle) or two 
commands (for a disk-to-tape and tape-to-disk cycle) . You can use DSC 
on-line or in either of its stand-alone versions (DSCSYS.SYS or 
DSC64K. SYS) . 

After a DSC copy operation, individual files are written in available 
contiguous blocks and the blocks available for new files are located 
in a contiguous area at the end of the new volume. If the contents of 
one disk are transferred to a disk with a larger capacity, the new 
disk takes on the attributes of the original disk except that 
additional storage space is available. 

DSC reads and writes data to its two buffers when it performs copy or 
compare operations. (See Figures 8-1 and 8-2.) Each buffer normally 
is large enough to contain four disk blocks and a 16-byte buffer 
prefix. However, the /Block Factor switch (/BL) in a DSC command line 
allows you to increase the number of blocks in each buffer, up to the 
maximum space available for DSC on your system. The maximum blocking 
factor is 4 for both stand-alone versions. 

In a disk-to-disk copy operation, DSC: 

1. Copies data from disk to a DSC buffer 

2. Copies data from the DSC buffer to another disk 
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In a disk-to-tape and tape-to-disk operation, DSC: 

1. Copies data from disk to a DSC buffer 

2. Writes data from the DSC buffer to tape 

3. Copies data from tape to a DSC buffer 

4. Writes data from the DSC buffer to another disk 

You can execute operations 3 and 4 to restore data to disk at any 
time . 




DISK INPUT DEVICE DISK OUTPUT DEVICE 

DSC reads eight (default) or more blocks of data from the disk input device to two 
buffers. 

In disk-to-tape copy operations, DSC writes data from the buffers to magnetic tape. 

In disk-to-disk copy operations, DSC writes data from the buffers to the disk output 
device. 

DSC repeats steps O and or © until it copies the entire input device. 

ZK-182-81 

Figure 8-1 Data Transfer for DSC Copy Operation 



o 

o 
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BLOCKS OF DATA 




DISK INPUT DEVICE 



DISK OUTPUT DEVICE 



o DSC reads four blocks (default) of data from the disk input device to a buffer. 
© DSC reads four blocks (default) of data from the disk output device to the second buffer. 
© DSC compares the contents of the two buffers. 
O DSC prints the differences on your terminal. 

DSC repeats steps O through O until it has compared the entire device. 

ZK- 183-81 

Figure 8-2 Data Transfer for DSC Compare Operation 



After a disk-to-disk copy operation, you can access the data on the 
new disk directly. However, after a disk-to-tape operation you cannot 
access the data on tape directly because it is stored in a format 
recognizable only to DSC. To access this data, you must perform a 
second DSC copy operation and transfer the data to another disk 
volume . 

When DSC copies and compresses a disk containing a saved system (a 
task image file created from an RSX-11M or RSX-11M-PLUS system image 
by an MCR SAVE command) , it moves all task files to different physical 
addresses. However, because the Task Control Block (TCB) entries for 
each task contain file identifications rather than Logical Block 
Numbers (LBNs) , such a saved system can function normally when it is 
rebooted . 



You can also use DSC to recover from hardware malfunctions that have 
made a portion of a disk volume unreadable. If the contents of a 
block allocated to a data file cause a read error, you can use DSC to 
copy the garbled contents to the output device and to generate a 
warning message labeling the garbled data block. You can then access 
the block and correct its contents. 
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8.1 DSC-SUPPORTED VOLUMES 

You can use DSC with a variety of mass storage or magnetic tape 
devices. The status DSC requires for the devices varies with the 
operating system. 

On RSX-11M systems, DSC requires unmounted volumes. 

On RSX-11M-PLUS systems, DSC requires volumes mounted within foreign 
characteristics* 

Table 8-1 lists the devices that can be used with DSC operations. 



Table 8-1 
DSC-Supported Devices 



Abbreviation 


Type 


Class 


DB 


RP04/RP05/RP06 disk pack 


Block 


structured 


DD 1 


TU58 cassette (DECtape II) 


Block 


structured 


UC 


DPI! /DC 1 1 f ; u Q/ 3 

Kf li/Koii nxcQ neau qisk 


Block 


structured 


Lit\ 


kruj/ Kj\UDr carurioge aiSK 


&J. KJ \* IV 




DL 


RL01/RL02 cartridge disk 


Block 


t~ r nc t" ii r prf 


DM 


RK06/RK07 cartridge 
disk 


Block 


structured 


DP 


RP02/RP03 disk pack 


Block 


structured 




dm n 9 /rm n /dm rm /rm r n /r po7 
disk pack 


Block 


structured 


DS 1 


RH70/RS03/RS04 and RH70/RS03/ 
fixed-head disk 


Block 


structured 


DT 1 


TU56 DECtape 


Block 


structured 


DU 2 
DXl 


RA80 Fixed media disk 
RX01 floppy disk 


Block 
Block 


structured 
structured 


DY 1 


RX02 floppy disk 


Block 


Structured 


MM 


TE16/TU16/TU45/TU77 
9-track magnetic tape 


Tape 




MS 


TS11 magnetic tape 


Tape 




MT 


TU10/TE10 7- or 9-track 
magnetic tape and TS03 
9-track magnetic tape 


Tape 




MF 2 


TU78 magnetic tape 


Ta pe 




1. Indicates that the device cannot be used with 


either 


stand-alone 



DSC. 

2. Indicates that the device cannot be used with DSCSYS.SYS. 
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8.2 INITIATING AND TERMINATING ON-LINE DSC 

You can initiate the on-line DSC in any of the ways explained in 
Chapter 1 of this manual. To terminate on-line DSC, type CTRL/Z. 

8.3 INITIATING AND TERMINATING STAND-ALONE DSC 

You can bootstrap stand-alone DSC (DSCSYS.SYS or DSC64K. SYS ) from disk 
or from tapes supplied with the operating system. 

You can bootstrap stand-alone DSC in one of two ways: 

1. Software boot stand-alone DSC by entering the privileged MCR 
BOOT command as follows: 

For Unmapped 

>INS $B00 

>BOO[T] [1, 50]DSCSYS.SYS 
For Mapped 

>INS $B00 

>BOO[T] [1, 51]DSC64K. SYS 

2. Hardware boot stand-alone DSC by loading the appropriate 
beginning bootstrap address. 

To create a hardware-bootable stand-alone DSC tape from the 
distribution disk, use the Virtual Monitor Console Routine 
(VMR) to save the system image to tape. 

When stand-alone DSC is booted, it displays the message: 

RSX-11S V3.0 BL32 DISK SAVE AND COMPRESS UTILITY V4. 
DSO 

The prompt indicates that DSC is ready to accept commands. Terminate 
stand-alone DSC by halting the processor. 

When DSC64K.SYS is booted, the Stand-alone Configuration and Disk 
Sizing Program (CNF) is active. Type the following for the DSC 
prompt : 

>RUN DSC 

Section 8.8 describes stand-alone DSC64K. SYS . 

8.4 DSC COMMAND FORMAT 

Commands for DSC use the format: 

DSC>outdev[s] : [filelabel] [/switch] =indev [ s] : [filelabel] [/switch] 
The parameters of this command format are: 
Output Parameters 
outdev: 

The physical volume (s) to which data is copied. The format for 
outdev: is dd[nn]: where dd are the ASCII characters for the 
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volume abbreviation, [nn] is an optional 1- or 2-digit octal unit 
number for the volume, and the colon (:) is required syntax for a 
device specification. If you omit the unit number, is the 
default. 

DSC uses tape drives in the order specified in the command line. 
If more tapes are required than specified, DSC accesses the tape 
drives available in round-robin fashion. Up to eight tape 
drives, separated by commas, can be specified as output devices 
in an on-line DSC operation. Stand-alone DSC permits only two 
tapes to be used as output devices. 

DSC ignores multiple disk specifications. 

file label 

Identifies the output disk's volume-ID, the tape file, or tape 
set that DSC creates in a data transfer. You can specify a file 
label with either disk or tape output volumes. If you do not 
specify a file label, and you copy a disk to tape, DSC records 
the volume ID of the input disk on the tape. When the copy is 
from tape to disk, the output volume ID defaults to the ID 
recorded on the tape. In a disk to disk copy operation, the 
output volume ID will default to the ID of the input disk. 

switch 

One or more of the optional switches described in Section 8.5. 
Input Parameters 
indev: 

The physical volume(s), in the format dd[nn]:, from which data is 
copied (see outdev:). 

file label 

Identifies the DSC-created tape file that is being transferred to 
disk or compared. If you do not specify a file label, DSC 
transfers the first file it encounters after its current position 
on the tape. DSC ignores the specification of an input file 
label when the input volume is a disk. 



NOTE 

Each file on a DSC-created tape set 
contains the contents of the disk copied 
by DSC. 



switch 

One or more of the optional switches described in Section 8.5. 



8.5 DSC FILE LABELS, SWITCHES, AND OPTIONS 

DSC commands can contain file labels and switches. Some switches also 
use options to specify values. Table 8-2 summarizes the DSC switches 
and options. Note that all of these switches can be used with both 
on-line and stand-alone DSC. See Table 8-5 for switches available 
only for stand-alone DSCSYS. 
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Table 8-2 
DSC Switches and Options 



Switch 



Format 



Description 



Append 



/AP 



Bad Block 



/BAD 



( MAN 
NOAUTO 
MANrNOAUTOl 
OVR 

MAN: OVR 



Block Factor 

Compare 
Density 



/BL=n 
or 
/BL:n 

/CMP 



/DENS=1600 
/DENS=800: 1600 
or 

/DENS: 1600 
/DENS: 800: 1600 
/DENS = 62 50 



Rewind 



Verify 



/RW 



/VE 



Appends a DSC file to the 
first volume of a 
tape set that already 
contains a DSC file. The 
latter file is currently 
the last file of the set. 



Allows manual entry of 
bad block locations; can 
supplement, override, or 
ignore the disk's bad 
block file. 

Sets the number of 256-word 
blocks DSC can include in 
each of its two buffers. 

Compares input and output 
volumes for differences. 

Overrides the DSC default 
storage density for magnetic 
tapes of 800 bits per inch. 
DENS=1600 creates magnetic 
tapes at 1600 bits per inch 
density and 800:1600 (the 
split density switch) 
creates tapes with volume 
headers at 800 bits per inch 
and the rest of the tape at 
1600 bits per inch. 

Note that the DENS=1600 
switch is valid with TU16, 
TU77, TE16, or TU45 drives. 
The DENS=800: 1600 switch 
is valid with TU16 or TU45 
drives when they are not 
controlled by the TM03 
formatter. The /DENS = 6250 
switch is only valid with 
TU78 drives. 

Rewinds all magnetic tapes 
before DSC executes the 
current command. 

Copies data from the input 
volume and compares it with 
data in the output volume. 
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8.5.1 File Label 

The file label identifies the data copied from a disk and stored on 
one or more tapes or on another disk. If you do not specify a file 
label, DSC uses the volume-ID of the input disk volume label as the 
output volume label. 

The file label can consist of from 1 to 12 alphanumeric characters. 
However, when copying to tape, DSC uses 9 characters to identify the 
file it creates which contains the disk's contents. Place the file 
label after the device specification and before any switches. 
Terminate the file label with one of the following: 

• An option switch 

• An equal sign (indicating the end of the output side of the 
command line) 

• A carriage return (indicating the end of the command line) 
For example: 

DSOMM01 : , MM02 : SYSFILE=DB 1 : 

DSC uses the file label SYSFILE in the command line to identify the 
file on tape that will contain the data to be copied from the input 
disk, DB 1 : . 

You can also use the file label when restoring data from tape to disk. 
If you enter a file label as part of the input specification, DSC 
searches the first volume for a file with that name. When it finds 
that file, DSC transfers it to the output volume. If, however, you do 
not specify an input file label, DSC transfers the first DSC-created 
file it locates on the first input volume. In both cases, using the 
/Rewind switch on the input side of the command causes the tape to be 
rewound before the search for the file starts. 

If you use a file label as part of the output specification, it will 
be used as the volume label of the output disk. If you do not specify 
an output file label, the default file label is that of the original 
input disk, (as recorded in its Home Block). 

For example: 

DSODB1: =MM01: ,MM02: SYSFILE 

In this command line, the /Rewind switch is not specified on the input 
side. Therefore, DSC searches the first volume specified, MM 01 : , 
beginning at the current position, for a DSC-created file named 
SYSFILE. If DSC finds SYSFILE on MM 01:, it completes the data 
transfer. If, however, SYSFILE is not found on the first volume, DSC 
issues an error message and terminates the operation. 

If you enter the command line without a file label, DSC transfers the 
first DSC-created file it finds to DB1: regardless of the file name. 
(This file may or may not be SYSFILE.) If you do not specify the 
/Rewind switch, the tape may or may not be positioned at the beginning 
before DSC begins its operation. 
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8.5.2 /Append Switch 

The /Append switch (/AP) directs DSC to begin writing a file to the 
first specified volume of a tape set that contains only DSC-created 
files. 

Enter the /Append switch as part of the output specification. The 
volume to which files will be appended must be specified as the first 
volume of the output side of the command line, as follows: 

outdev: [f ilelabel] /AP=indev : [filelabel] [/switch] 

When you use the /Append switch with the output specification, DSC 
searches from the current position on the first specified tape output 
volume for the last logical end-of-file (EOF) created by a previous 
DSC command. If the last DSC-created file does not end on that 
volume, DSC terminates the operation and issues the following message: 

OUTPUT TAPE ddnn: IS FULL 

If the first specified tape output volume contains a portion of a DSC 
file that began on a previous volume, DSC terminates the operation and 
issues the following error message: 

OUTPUT TAPE ddnn: IS A CONTINUATION TAPE 

If DSC locates the end of a file on the tape that began on another 
volume, DSC terminates the operation and issues the following error 
message : 

OUTPUT TAPE ddnn: IS NOT THE ONLY REEL IN ITS SET 

For example: 

DSOMM01: , MM : SYSFILE/RW/AP=DX1 : 

This command line appends the contents of DX1: to the last 
DSC-created file already present on the first output volume specified, 
MM01 : . Since the /Rewind switch is specified (see Section 8.5.7), DSC 
first rewinds the tape on MM 01 : and searches for the last EOF block 
on the tape. When it determines that only complete DSC-created files 
exist on the volume on MM 01 : , DSC appends the new file, SYSFILE, to 
the file or files already on the tape. If necessary, DSC extends 
SYSFILE to additional volumes. 

You can only use the /Append switch with output tape volumes. Any 
other use of the switch causes DSC to generate an error message and 
terminate the operation. 



8.5.3 /Bad Block Switch 

Use the /Bad Block switch (/BAD) with output disk volumes to control 
the way DSC uses bad block information. 

The options for the /BAD switch allow you to: 

1. Supplement the output disk bad block file with manually 
entered bad block data. 

2. Ignore or override the bad block file on last track 
(manufacturer's list of bad blocks) or non-last-track 
devices . 

3. Use only manually entered bad blocks. 
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The bad block descriptor of the disk is never altered by DSC. 

If the /BAD switch is not specified, DSC will access the bad block 
descriptor area (the last good block on non-last-track disks or the 
entire last track on last-track disks) to obtain the information to 
create the bad block file, BADBLK. SYS . If DSC determines that the 
descriptor area is invalid, DSC displays a warning message (see 
Message 59 ) . 

The format for the /BAD switch and its options are: 

/BAD=MAN 
/BAD=NOAUTO 
/BAD=MAN: NOAUTO 
/BAD=OVR 
/BAD=MAN: OVR 

NAN 

Supplements BADBLK. SYS with manually entered bad block data. 
This option may be combined with either NOAUTO or OVR to produce 
two more options. 

NOAUTO 

Ignores the bad block descriptor area on the disk. Note that in 
this case, DSC will attempt to write in any block it selects. 
This option may be combined with MANUAL to produce the option 
MAN: NOAUTO. 

MAN: NOAUTO 

Enters only manually entered bad block data in the bad block file 
BADBLK. SYS. Thus, DSC bypasses only manually entered bad blocks 
when selecting blocks to write in. 

OVR 

Ignores the bad block descriptor area and accesses the substitute 
descriptor area (the last good block on the next to the last 
track on the disk) to obtain the data for the creation of 
BADBLK. SYS. This option is valid only on last-track devices. 
This option may also be combined with MAN to produce the option 
MAN: OVR. 

MAN: OVR 

Allows manual entry of bad block data to the bad block file 
BADBLK. SYS. 

When you specify MAN, MAN: NOAUTO, or MAN: OVR with the /Bad switch, DSC 
responds with the following prompt: 

DSC>LBN(S)= 

DSC issues this prompt after it accepts the original command line but 
before it transfers any data. 

Enter the locations of bad blocks after the LBN(S)= prompt as follows: 
DSC>LBN(S)=n:m 
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The logical block number (LBN), in octal, of the initial bad 
block in the group. 



The number, in octal, of consecutive blocks contained in the 
group. If you do not specify m, it defaults to 1. 

To specify a decimal number for either m or n, place a period (.) 
after the number. 

You can specify multiple bad block entries on one command line using 
either a space, tab, or comma to separate each entry. You can also 
use separate lines for each entry. 

After you enter the first group of bad blocks, DSC reissues the 
LBN(S)= prompt. At this point, you can enter additional bad blocks. 

To terminate manual bad block entry, enter a carriage return after the 
LBN(S)= prompt. 

When you have entered all the bad blocks and terminated the entry 
process, DSC begins the data transfer. 

For example: 

DSC>DB1:/BAD=MAN:NOAUTO=MM01: ,MM02 : SYSFILE/RW 

DSC>LBN(S)=702: 7<TAB>644: 2 

DSC>LBN(S)=4057, 5001: 3 

DSC>LBN(S)=<RET> 

DSO 

DSC restores the output disk, DB 1 : , from the tape file SYSFILE 
contained on MM 01 : and MM02:, skipping only the blocks you entered 
manually. In the previous example, the following blocks will not be 
used : 

702 644 4057 5001 

703 645 5002 

704 5003 
705 

706 
707 
710 

Compare the previous example with the following example: 

DSC >DB 1 : /BAD=NOAUTO=DB : 

This example transfers data to the lowest LBNs on DB1: regardless of 
the content of the resident bad block descriptor. 

If you specify /BAD=0VR on a last track device, DSC reads the last 
good block written by BAD on the next to the last track of the device. 
The information in this substitute descriptor block is used to create 
the bad block file. If MAN:0VR is specified, manually entered blocks 
will be added to the bad block file. 
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8.5.3.1 Obtaining Bad Block Information - You can obtain bad block 
information in two ways: 

1. Running the Bad Block Locator program (BAD) , described in 
this manual 

2. Running the DIGITAL Field Service stand-alone diagnostic 

The BAD utility automatically provides bad block information and 
creates a bad block file that DSC can use. 

The Field Service stand-alone diagnostic reads every word in a block 
and displays bad block messages on the console terminal. (This 
diagnostic is recommended for the user who wants more comprehensive 
testing of a volume). However, since the output is the physical 
address of each bad block, you must convert this address to logical 
block numbers before DSC can use it. 



8.5.3.2 Conversion to Logical Block Numbers - All DSC bad block 
information must identify bad blocks by LBN. 

The manufacturer-furnished or diagnostic bad block information usually 
identifies bad blocks by physical address (sector-track-cylinder) . 
Before you enter this information manually for DSC, convert the 
physical addresses to LBNS. Use the following formula: 

(((cylinder number*tracks/cyl inder ) +track number) *sectors/track) +sector number 

For example, suppose a bad sector of an RP06 (19 tracks per cylinder 
and 22 sectors per track) has the following physical address: 

Octal Decimal 



Cylinder Number = 536(8) 350. 

Track Number = 16(8) (14.) 

Sector Number = 13(8) (11.) 

The LBN for the example is calculated as follows: 



( ( (3 50.*19.)+14.)*2 2.)+11.=146619. 



8.5.4 /Block Factor Switch 

The /Block Factor switch (/BL) allows you to set the number of blocks 
DSC uses in each of its buffers during I/O operations. The default 
DSC block factor is four blocks or the last value specified with the 
/BL switch. 



8.5.4.1 Using the /BL Switch - The format for the /Block Factor 
switch is: 

outdev: [f ilelabel] /BL=n=indev : [filelabel] 
Note: /BL:n will also be accepted. 

The value of n can be any positive integer, decimal or octal, less 
than or equal to the maximum block factor available to DSC. This 
maximum depends on the amount of memory DSC can access under the 
system configuration. (See your system manager for this information.) 
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The /BL switch can be specified either on the input or output side of 
a DSC command line. 

Note, if the input volume is tape, DSC determines the block factor 

from the header label of the. input file and ignores the /BL switch. 

If you specify the /BL switch on both sides of a DSC command line with 
a disk volume, DSC uses the last value it receives, that is, the one 
from the input side of the command line. However, if you specify the 
/BL switch only on the output side of a command line, DSC uses that 
value . 

DSC requires 2020(8) bytes of memory for each additional block of 
buffer space you specify. If the /BL switch in a DSC command line 
requires more memory than DSC has available, DSC displays the message 
BAD BLOCKING FACTOR and exits. 

For example: 

DSC>DB1:/BL=11=DB0: or DSC>DB1:/BL: 11=DB0: 

In this example, DSC attempts to increase the number of blocks in each 
of its buffers to 11. DSC requires an additional 16160(8) bytes of 
memory for the expansion (7 additional blocks times 2020(8) bytes). 

If DSC does not have access to 16160(8) additional bytes of memory on 
your system, it will display the error message BAD BLOCKING FACTOR. 

If the expansion succeeds, DSC reads and writes 11 blocks of data at 
one time during an I/O operation instead of 4. This decreases the 
time required for DSC operations. 

Once DSC has expanded its buffers to the value of the /BL switch, that 
value becomes the default value. DSC does not reduce its task image 
size if a command line is executed at a lower block factor. However, 
if you specify a lower block factor in a subsequent command line, DSC 
will create that volume at the lower factor. 



8.5.4.2 System-Dependent Requirements for /BL Switch - On-line DSC on 
a mapped system expands automatically if memory is available. (See 
the RSX-11M System Generation and Installation Guide for details of 
building DSC with additional memory.) 



Table 8-3 

Operating System Limits for DSC Block Factor 



Operating System 


Default 
Blocking 
Factor 


Max imum 
DSC 
Size 


Max imum 
Blocking 
Factor 


RSX-11M/M-PLUS 








Mapped Systems 


4 


32K words 


36 (10) 


RSX-11M 








Unmapped Systems 1 


4 


20K words 


10 (10) 



1. On unmapped RSX-11M systems, the DSC task must be rebuilt with 
additional memory for the block factor to be increased beyond 4. 
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NOTE 

If you create DSC tapes at a blocking 
factor greater than 10, they will be 
unusable on unmapped RSX-11M systems. 
Such systems can only use DSC tasks of 
20K words. 



8.5.5 /Compare Switch 

The /Compare switch (/CMP) directs DSC to compare the contents of two 
disks or a disk and a tape set. Multiple tape specifications are 
valid, but multiple disks are not. The /Compare switch is always 
specified on the output side of the DSC command line. If the 
comparison involves tape and disk, specify the tape as the input 
device. The /Compare switch performs only comparison operations; no 
copy operation is involved. 

To perform both a copy and compare operation, use the DSC /Verify 
switch (see Section 8.5.8). 

Specify the /Compare switch as follows: 

outdev: [f ilelabel] /CMP=indev : [filelabel] 

When DSC finds a difference between the volumes it is comparing, it 
displays a warning message on your terminal. This warning message 
lists the output volume number, file identification, and the Virtual 
Block Number (VBN) where the difference was found. DSC then continues 
the comparison. 

When DSC detects an end-of-volume (EOV) on any reel or end-of-file 
(EOF) on other than the first reel of a tape set, the /CMP switch 
causes DSC to rewind and unload the current volume and resume 
comparison with the next volume until it detects an EOF. 

When DSC begins a comparison involving tape, it first positions the 
specified or implied file as described in Section 8.5.7. DSC 
positions a single volume tape at the end of the current file when the 
comparison ends. Each reel of a tape set is rewound and unloaded as 
the compare operation for it is completed. DSC then resumes the 
comparison using the next volume of the set. 



8.5.6 /Density Switch 

The Density switch, with its two options, allows you to override the 
DSC default storage density of 800 bpi for TU16, TE16, TU77, and TU45 
tape drives and 6250 bpi for the TU78. The following two sections 
discuss these options. Although you can use other tape drives with 
DSC, only these drives can support the /Density switch. 

You do not have to specify the /Density switch when a tape is the 
input device. DSC determines the density of all input tapes by first 
reading the tape at 800 bpi and then, if that fails, reading it at 
1600 bpi. In the case of the TU78, DSC first reads the tape at 6250 
bpi, then, if that fails, it reads the tape at 1600 bpi. 

If you specify the /Density switch with a disk, DSC issues an error 
message and halts the operation. 
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If you specify the /Density switch with tape drives other than those 
above, DSC ignores the switch and does not alter the default density. 
Note that TS11 (TS04) drives write all tapes at 1600 bpi and cannot 
support 800:1600. The TS11 (TS04) ignores the /Density switch, 
therefore do not use it with these devices. 



8.5.6.1 1600 bpi Option - The 1600 bpi Option directs the TU16, TE16, 
TU77, TU78, or TU45 drive to operate as an output volume at a density 
of 1600 bpi. The drive then writes all volumes in the tape set at 
that density. For example: 

DSOMM01: ,MM02: SYSFILE/RW/AP/DENS=1600=DB 1 : 
In this example, MM 01 : and MM02:, are written at 1600 bpi density. 



8.5.6.2 Split Density Option - The Split Density Option 

(/DENS=800: 1600) directs the TU16 or TU45 drives (using the TM02 tape 
formatter) to write the entire tape set, except for the first two 
blocks on the first volume, at 1600 bpi. The first block on the file 
contains the volume label and the second block is a dummy boot block 
that displays the following error message if an attempt is made to 
boot the volume: 

THIS VOLUME DOES NOT CONTAIN A BOOTABLE SYSTEM 

In the following example, DSC records the first two blocks of the 
first volume at 800 bpi and the remainder of the file at 1600 bpi. 

DSOMM01: ,MM02 : SYSFILE/RW/DENS=800 : 1600=DB1: 



NOTE 

Magnetic tapes created using the Split 
Density Option do not comply with 
American National Standard X3. 27-1978. 



You cannot use the Split Density Option with the TE16 magnetic tape 

drive. Tape drives controlled by a TM03 also cannot use the split 

density option. The TM02 controller, however, does support the split 
density option. 



8.5.7 /Rewind Switch 

The Rewind switch (/RW) directs DSC to rewind all volumes in a tape 
set before performing any other DSC operation, such as a copy or a 
compare operation. You can use it to rewind either input or output 
volumes (see Table 8-4). 

The /RW switch can be used only with magnetic tapes. If you use it 
with any other volume, DSC prints an error message. 
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INPUT 

If you enter the /RW switch as part of the input specification, DSC 
rewinds only the first tape before the DSC operation begins. The 
other tapes are rewound before they are about to be accessed. If you 
specify a file label with the /RW switch, DSC rewinds the tapes and 
searches for the file you specified from the Beginning of Tape (BOT) 
on the first volume. If you do not specify a file label, DSC 
transfers the first DSC-created file it encounters on the first 
volume. 

After a volume of a tape set has been copied, DSC rewinds it and 
places it offline. If, however, the current file ends on the first or 
only tape of a set, the tape is positioned to read the next file on 
the input tape. The /RW switch only rewinds tapes at the beginning of 
a DSC operation. 

OUTPUT 

If you enter the /RW switch as part of the output specification, DSC 
rewinds the output tape before beginning a copy or compare function. 
The default is no rewind and the tape is not moved. 

If you do not enter the /RW switch with the output specification and 
the first volume is not positioned at BOT, DSC begins its operation 
after the last DSC-created EOF it finds on that volume. 

After the output tape has been rewound, DSC determines if the tape is 
positioned at the beginning (BOT). For a compare function, a search 
for the next file or a specific file begins at the current tape 
position. For a copy function, if the /Append switch was specified or 
if the tape is not positioned at BOT, the search for the current end 
of DSC created files begins (see Section 8.5.2); otherwise, the copy 
operation will overwrite any data previously stored on the tape. 

Table 8-4 summarizes the use of the /Rewind switch with various DSC 
operations, with and without a file label. 

An example of the use of the /Rewind switch follows: 

DSOMM01 : SYSF ILE/RW=DB 1 : 

DSC rewinds the volume on drive MM01: and overwrites any data on the 
tape. The contents of DB1: are written to a single file identified 
as SYSFILE. DSC does not rewind the tape when the operation is 
finished unless the file extends to another volume. If the file does 
extend, DSC rewinds and unloads the filled tape. DSC ensures that 
subsequent tapes are at BOT before using them for read or write 
operations. Each subsequent volume, including the last one in the 
tape set, is rewound and unloaded when it is filled. 

The following example shows the restoration of a DSC-created file: 

DSODB1: =MM02: ,MM01 : SYSFILE/RW 
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Table 8-4 

The /Rewind Switch and DSC Operations 



Switch 


Specification 


File Label 


Action 


/RW 


Input/Output 


With/without 


Rewinds first tape 
before copy 
operation begins. 


/RW 


Input 


With 


DSC searches for 
specified file 
from the beginning 
of the first tape 
volume before a 
copy/compare 
operation begins. 


/RW 


Input 


Wi thout 


DSC copies/ 
compares the first 
file it encounters 
on the first 
volume . 


/RW 


Output/With 


File labels 
specified when 
tape is output 
volume are 
ignored when 
the tape is 
restored to 
disk . 


DSC writes data, 
starting at the 
beginning of the 
first tape volume, 
unless /AD is 
specified . 


No 

Rewind 
Swi tch 


Output 




If the tape is not 
at BOT, DSC writes 
data, beginning 
after the last 
end-of-file block 
it encounters. 

(If tape is 
already at BOT, 
and the /AP switch 
is not specified, 
DSC starts there.) 

During copy 
operations to 
multiple tapes, 
DSC rewinds the 
tape as it is 
filled and takes 
it offline. 
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In this example, DSC restores a volume (DB1:) by using a tape set 
created by a previous DSC operation. DSC rewinds the first volume on 
MM02: and searches for a previously created DSC file labeled SYSFILE. 
If the file is found, DSC transcribes it. If it is not found on 
MM02:, DSC issues a message and terminates the operation. DSC will 
not search MM 01 : if the file does not begin on MM02:. Each volume of 
the tape set is rewound and unloaded when the data it contains has 
been copied or compared. If SYSFILE ended on MM02: the first time it 
was accessed, the tape is not rewound and unloaded but is positioned 
to access the next file. 



NOTE 

When you refer to tapes after your 
system is booted, you must use the 
/Rewind switch. If you do not use the 
switch, the tape driver will return an 
error message. 



8.5.8 /Verify Switch 

The /Verify switch (/VE), entered as part of the output specification, 
directs DSC to perform a copy operation followed by a compare 
operation to verify that the two volumes are the same. (DSC does not 
allow you to specify either the /Verify or /Compare switch if both 
input and output volumes are tape.) 

If either the input or output volume is tape, the Verify operation 
takes place at the end of the Copy operation for each volume. In 
other words, DSC writes MM01: and compares MM01:, then writes MM02: 
and compares MM02:, after which the entire DSC operation is complete. 
In a disk-to-disk DSC operation, the verify operation begins when the 
copy operation is finished. 

You specify the /Verify switch as follows: 

outdev: [f ilelabel ] /VE=indev : [filelabel] [/switch] 

If you do not specify a file label for an input tape set, DSC will 
copy the first file it finds on the first volume of the set. 

When DSC detects EOV or EOF on any volume of a tape set during a copy 
operation, it repositions the volume to the beginning of the current 
file segment and begins the verify operation. 

During a verify operation, if DSC detects EOV on any volume, or EOF on 
other than the first volume of a tape set, it rewinds and unloads the 
tape when the operation is complete. After an EOV, the copy operation 
resumes using the next volume from the beginning of the tape. 



NOTE 

If you specify a tape as one of the 
volumes, DSC requires extra time after 
the copy operation to rewind the tape 
and search for the current file before 
it begins to verify. 
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8.6 DSC OPERATION OVERVIEW 

DSC initially accesses the first primary file header and writes the 
blocks mapped by its retrieval pointers to the output volume. DSC 
then checks the primary file header to determine whether it points to 
any extension headers. If extension headers exist, DSC transcribes 
them and the blocks they map until the entire file, with all of its 
extensions, has been written to the output volume. DSC then accesses 
the remaining primary file headers in numerical order. For example: 

DSODB1: =DB2: 

In this example, DSC copies all the files on DB2: to DB1:. 

When DSC copies file extensions it updates the output retrieval 
pointers and file linkages involved in the transfer as required. This 
not only involves collapsing retrieval pointers, but also reduces the 
number of file extensions required as the retrieval pointers are 
el iminated . 

As a result of a copy operation, each primary file header is followed 
by all of its extensions. Volumes created in a copy operation have 
complete files written to contiguous blocks (except where blocks have 
been flagged as bad in earlier operations on the volume). DSC writes 
data, beginning at the lowest LBN possible on the disk. 

If an input file is contiguous, DSC will search for an area on the 
output volume with enough contiguous blocks to contain the file. If 
no such area exists, DSC will issue an appropriate message and 
terminate the copy operation. 

If an input file is not contiguous, data is allocated in as few 
contiguous sections as possible, in the first unoccupied blocks 
available on the output volume. 

Before the actual copying of data to a disk begins, DSC must, in 
effect, initialize the disk. This process might take several minutes 
if there is a maximum number of files allocated in the Index file. 
Although it might appear that DSC is in a loop during this period, it 
is actually zeroing out all headers in the Index file. 



8.7 STAND-ALONE DSC - DSCSYS.SYS 

Stand-alone DSC DSCSYS.SYS does not support all the features of the 
on-line version. DECtapes, floppy diskettes, DF/DS fixed-head disks, 
and TU58 cassettes cannot be used with the standalone version. In 
data transfer operations, stand-alone DSC uses all of the switches 
described in Section 8.5. 

The system data base in the stand-alone version has a Device Control 
Block (DCB) for each supported device type. The DCB points to a Unit 
Control Block (UCB) for logical unit and for logical unit 1. Except 
for MS tapes, the UCBs for a specific device type point to a common 
Status Control Block (SCB) which contains the CSR and Vector Addresses 
associated with the related controller as listed in Table 8-6. 
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Since MSO: and MSI: require unique CSR and Vector addresses, their 
respective UCBs point to separate SCBs . The format of the system data 
base imposes the following restrictions: 

• Logical unit numbers are limited to and 1. 

• Only one controller per device type (except MS tapes) is 
supported per command. 

• DP and DR type devices have been assigned nonstandard vector 
addresses to avoid possible conflict with DB devices. 
Similarly, MT and MS tapes have been assigned nonstandard 
vector addresses to avoid possible conflict with MM tapes. 

You can overcome some of these limitations by using the four switches 
listed in Table 8-5 to alter the system data base default values to 
match your system. A mismatch of either the CSR or Vector address 
will cause the stand-alone system to fail. The switches can be used 
only with stand-alone DSC. 



Table 8-5 
Stand-Alone DSCSYS.SYS Switches 



Format 


Switch 


Description 


/CSR=xxxx 


/Control Status 
Register switch 


Specifies control status 
addresses for a specific 
SCB. 


/TM02=x 


/TM02/TM03 Formatter 
switch 


Specifies the physical 
unit number of the 
formatter on the 
RH11/RH70 controller. 


/UNIT=x 


/Unit switch 


Specifies the physical 
unit that will be 
referenced by the 
indicated UCB. 


/VEC=xxx 


/Vector Address 
swi tch 


Specifies the vector 
address for a specific SCB. 



The four switches supplied with stand-alone DSC can appear together in 
a single command line to specify the appropriate values of a single 
device or device type. However, you can only specify values for one 
device type or generate one data transfer operation in a single 
stand-alone DSC command line. 

Therefore, when you use these switches, you must enter at least two 
command lines: one to specify the switches with a device or device 
type and one to initiate the DSC data transfer operation. 



NOTE 

Once you use the switches, DSC uses them 
in all subsequent command lines until 
you either specify new switches in a new 
command line or terminate DSC, 
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The general format for a stand-alone DSC command with switches is: 
DSOddnn :/switchl=x. . ./switchn=y 

ddnn: 

The device identifier and unit number specifying the DCB and UCB 

/switchl. • ./switchn 

One or more of the stand-alone switches described in the 
following sections 

x,y 

The values you assign to the switch(es) 
8.7.1 /Control Status Register Switch 

Use the Control Status Register switch (/CSR) to alter the device 
Control Status Register address generated by stand-alone DSC so that 
it conforms to the address required by your system for a particular 
device . 

Table 8-6 lists the CSR and vector addresses of the device types 
supported by stand-alone DSCSYS.SYS. 



Table 8-6 

System-Generated CSR and Vector Addresses 



Device Type 


CSR 


Vector 


DB: 


176700 


254 


DK: 


177404 


220 


DL: 


174400 


160 


DM: 


177440 


210 


DP: 


176714 


300 1 


DR: 


176700 


320 1 


MM: 


172440 


224 


MT: 


172522 


320 1 


MSO: 


172522 


320 1 


MSI: 


172526 


330 1 


MF: 


175400 


260 



1. Indicates nonstandard vector address. 
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The following example illustrates the correct use of the /CSR switch: 

DSC>MM1:/CSR=160546 
DSC>DB0:/CSR=16 0646 

In this example, DSC has set the CSR addresses of the MM1: tape drive 
and the DBO: disk drive to 160546 and 160646, respectively. After 
you enter these values, you can enter another DSC command line to 
initiate a copy and/or compare operation. Neither of the commands 
that use the /CSR switch in the example cause a copy operation to 
beg in . 

If a DSC operation involves multiple devices of the same type, only 
specify the /CSR switch once for each device type. (The exception is 
the MS: tape drive; each drive must be set to its correct CSR on the 
host system.) 



8.7.2 /TM02 Switch 

Use the /TM02 switch (/TM02) to specify the physical unit number of 
the TM02/TM03 formatter, associated with a particular UCB on the RH 
controller for your system. This switch need only be used if that 
physical number differs from the current value. Do not confuse this 
number with the physical number assigned to a particular tape drive. 

Stand-alone DSC is created with a physical unit number of assigned 
to the TM02/TM03 formatter on the RH controller. This assignment 
affects each of the two UCB's for MM tapes. You can change this to 
any octal digit from 1 to 7 for each MM: device. For example: 

DSC>MM1:/TM02=1 

This command line alters the physical unit number of the formatter 
associated with MM1: from its current assignment on the RH controller 
to 1. The /TM02 switch affects only the specified device. If MMO: 
also requires a change, the command must be repeated specifying MMO:. 
If MMO: and MM1: are associated with different RH controllers, they 
cannot appear in the same command line. The /TM02 switch only works 
with MM: devices. It cannot be specified with an MT:, MS:, or a disk 
device . 



8.7.3 /Unit Switch 

You can use the /Unit switch (/UNIT) to change the unit numbers DSC 
accepts for device specifications. Stand-alone DSC is generated with, 
and accepts only, two logical unit numbers, and 1. This constraint 
can be amended somewhat with the /UNIT switch. The numbers and 1 
must still be specified in the command line, and the number of devices 
cannot be increased. However, DSC can access devices with physical 
numbers other than and 1. For example: 

DSC>DP1:/UNIT=5 

This command will initiate a copy from the DP currently designated as 
physical unit 5 to DPI:. 

DSODP1: =DP0: 

In this command, the output device is the DP currently designated as 
unit 1 unless the /UNIT switch had previously been applied to DPI:. 
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8.7.4 /Vector Address Switch 

Use the /Vector Address switch (/VEC) to change the stand-alone DSC 
vector addresses to the addresses required by your system. Each unit 
of the device type is accessed by the specified vector address. For 
example : 

DSC>DB1:/VEC=3 20 

After you enter this command line, all DB:-type devices will be 
accessed with a vector address of 320. 

Stand-alone DSC uses nonstandard vector addresses to resolve 
conflicting unit configurations. These conflicts occur when a system 
contains : 

• MM, MT, or MS device types such as a TU16, TE10/TU10 or a TS03 
drive, for example. 

• Any combination of RP02/03, RP04, 05/06/07, and RM02/03/05/8 
(such as an RP02 disk and an RP04 disk) . 

For example, before you can reference MM, MT, or MS tapes, you must 
use the /VEC switch to change the DSC vector setting of 320 to the 
correct value for your system. 

DSC>MT1:/VEC=224 

After you enter this command line, all MT devices will be accessed 
with a vector address of 224 (instead of the DSC-generated vector 
address of 320) . 

The /VEC switch applies to all drives of the same type except in the 
case of MS:, where only the specified device is affected. 

If the /VEC switch is not used to alter the DSC setting, DSC waits for 
a response from the incorrect vector address. This response never 
comes. 



8.8 STAND-ALONE DSC - DSC64K. SYS 

DSC64K is similar to the on-line version of DSC with the following 
exceptions : 

• DSC64K is not overlaid 

• DT, DX, DY, DD, DF, DS devices are not supported 

• Only one tape may be referenced either as input or output 

• The maximum blocking factor is 4 

This version is essentially an RSX-11M system with BAD, FMT, DSC, and 
CNF fixed in memory, and requires 64KW of memory. When 
[1, 51]DSC64K. SYS is software booted, the system comes up with CNF 
active . 
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CNF is the Stand-alone Configuration and Disk Sizing Program. It 
lists the switches you can use and then prompts you for the first 
device type for which you would like the CSR and vector information. 
It is recommended that you first specify /DEV to find out the status 
of devices on your system. You can also use CNF and its switches to 
set the CSR and vector addresses of devices in your system or to 
change the default formatter number (FOR=n) for some of the magnetic 
tape devices. (The functions of these switches correspond to the 
switches listed in Table 8-5 for DECSYS.SYS.) 

The CNF switches are: 

/CSR=nnnnnn 

Changes the default CSR for the device. 

/DEV 

Lists the default CSR and vector addresses for all of the 
devices . 

/FOR=n 

Changes the default formatter number for some of the 
magnetic tape devices. The switch is only valid for MF:-and 
MM:- type devices. The initial default for n is 0. 

/VEC=nnn 

Changes the default for the device. 

CNF will prompt you for the first device you want to reference. If 
adjustments are required for the device, use the appropriate CNF 
switch(es). For example, to alter the vector and CSR values for MT:, 
type the following: 

MT:/VEC=nnn/CRS=nnnnnn 

After the system data base has been adjusted with the new values, CNF 
prompts you for the second device. The response will be similar to 
the response for the first device. CNF will then request that you 
press the RETURN key to return control to MCR. Use the RUN command to 
activate any one of the four installed utilities. 

The DSC64K system image (DSC64K. SYS ) and symbol table (DSC64K.STB) are 
located in UFD [1,51] on the following disk volumes: 

BIG DISK KIT - RSXMBL31 

RK06/RK07 KIT - CLISRC 

RL01/RL02 KIT - RLUTIL 

RK05 KIT - DCLSRC 



8.9 DSC DATA TRANSFERS 

As outlined in the beginning of this chapter, DSC's complete data 
transfer process consists of either a direct disk-to-disk operation or 
a two-step, disk-to-tape/tape-to-disk operation. DSC reads and writes 
data to and from its own internal buffers during these operations. 

The following sections describe DSC's operation in each of these data 
transfers . 
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8.9.1 Data Transfer from Disk 

After you enter a DSC command line specifying a copy operation from a 
disk, DSC scans the input disk to ensure that it is in Files-11 
format. DSC begins by copying an approximation of the disk index 
file. Because this file is updated to reflect the status and location 
of blocks as they are allocated on the new disk, the index file bit 
map, the storage bit map file, and the bad block file are not 
transcribed exactly: DSC transcribes only the data necessary for the 
construction of these files on the new disk. However, the index file 
bit map still reflects the maximum number of files on the input disk. 

DSC accesses the input volume index file's active file headers in 
numerical order to locate the next active primary file header. DSC 
transfers that header, the blocks it maps, and all extension headers 
and related blocks that are part of the file, to the output medium. 
It then accesses the next active primary file header from the index 
file. DSC continues this operation, each time writing a complete 
file, until it has transferred all the active files. 

DSC accesses and transcribes only the blocks allocated to active 
files. It ignores unallocated blocks interspersed throughout the 
input disk. This results in contiguous data blocks on the output disk 
following the copied files. 

If DSC accesses a file that contains bad data, DSC transcribes 
whatever it reads from the block. When DSC restores the file to disk, 
it writes the block's contents as it originally read them. The 
logical block still contains garbled data, but the new physical block 
can be accessed and its contents corrected. A message identifying 
these bad areas is displayed on the console terminal. 

In summary, to transfer data from a disk, DSC: 

1. Verifies that the disk is on line and in Files-11 format. 

2. Transcribes disk index files, updated for their new status. 

3. Reads the data to a DSC buffer. 



8.9.2 Data Transfer to Tape 

When the output volume in a DSC operation is tape, DSC writes the 
contents of the input disk to a tape on the drive you specify. This 
data transfer usually involves multiple reels of tape (a tape set) and 
multiple tape drives. 

The tapes that DSC creates serve as a backup of the disk's contents. 
You can only use DSC-created tapes by copying them back to a disk and 
restoring the disk's contents to their original form. Although the 
tapes contain many individual files from the input disk, DSC treats 
the tapes as if they contained a single file — a file of the disk's 
entire contents. 

When DSC begins writing the disk's contents to tape, it allows writing 
to more than one volume. The first block DSC writes to tape is a 
header that contains the volume name (obtained from the file label) 
and the relative volume number. This header identifies the tape set 
and the volume's place within that set. It ensures that when DSC 
begins to restore the disk, it will load each volume in the tape set 
in order. 
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After the header, the tape set includes the data required to 
reconstruct directory files, maps and pointers, and the actual files 
copied from the disk. 



NOTE 

When the disk is restored, the directory 
files are at the beginning of the disk, 
regardless of their position on the 
original disk. 



To initiate the copy operation, first ensure that the tape devices are 
online. You can specify multiple tape drives in the following way: 

DSOddnn (0) : ,ddnn (1) : , . . .ddnn (7) : [f ilelabel] =indev: 

An example of a command in this format is: 

DSOMM0: ,MM1: ,MM4: , MM 2 : S YS F I LE =DB 1 : 

You have the option of entering a file label in this command line 
after specifying the last device. You can specify only one type of 
tape drive, either MM or MT or MS, in a single DSC command line. 
Although you can specify up to eight drives on the output side of the 
command line (two drives in stand-alone DSC), you can specify each 
drive only once. 

If the number of volumes in the tape set exceeds the number of tape 
drives available, DSC uses volumes on the specified drives in 
round-robin fashion. Using the previous example, the order of 
replacement until an end-of-file is reached would be as follows: 

MMO: MM1 : MM4: MM 2: MMO: MM1: MM 4: MM 2: ... 

In summary, to transfer data to tape, DSC: 

1. Verifies that the first or only volume of a tape set is 
on-line and wri te-enabled . 

2. Verifies that subsequent volumes of a tape set are at 
Beginning of Tape (BOT) , on-line when required, and 
wr ite-enabled . 

3. Transcribes data from a DSC buffer to the tape. 



8.9.3 Data Transfer from Tape 

DSC can only use the tapes it creates to (1) reconstruct a disk or (2) 
perform compare and verify operations. 

When you mount the tapes and specify tape drives as input devices, DSC 
sequentially accesses and writes the tape contents to the output 
volume. Up to eight drives may be specified on the input side; they 
will be referenced in round-robin fashion as described in Section 
8.9.2. As it transfers the data, DSC creates and updates directory 
files . 

Tape drives specified as input devices must be on line. The volumes 
in the tape set must be referenced in the correct order in the command 
1 ine . 
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If you specify a file label, DSC transfers only the contents of the 
file identified by that label. If you do not specify a file label, 
DSC transfers only the first DSC-created file it encounters on the 
first volume of a set. 

In summary, to transfer data from tape, DSC: 

1. Verifies that the tape drives are on line. 

2. Accesses the volumes in a tape set in round-robin order. 

3. Creates directory files. 

4. Reads the data to a DSC buffer. 



8.9.4 Data Transfer to Disk 

A DSC operation is not complete until the data involved in the 
transfer is restored to disk. 

To receive input, a disk must be on line. Any disk large enough to 
contain all the input data can be specified as the output disk when 
the data is restored to the original disk. 

The disk should have an up-to-date bad block descriptor or have bad 
block data entered in a DSC command line with the /BAD switch. This 
ensures that the data written on the disk will be accessible. You can 
update the bad block descriptor before a DSC operation by running the 
BAD program (see Chapter 6). 

After identifying the bad blocks on the output disk, DSC examines that 
disk to ensure that it has enough free blocks to contain all the data 
to be transferred. DSC compares the number of blocks to be 
transferred from the input disk(s) with the number of blocks available 
on the output disk. DSC issues an error message and exits if too few 
blocks are available. 

DSC constructs the index and storage bit map files when it begins 
transcribing files. DSC updates the file headers to reflect the 
location of the data on the new disk. This updating is required 
because blocks that were previously scattered are now copied to a 
contiguous set of blocks, beginning at the lowest LBN available on the 
disk. DSC will write the primary file header, its contents, and 
associated file extension headers and the extensions they map as a 
unit to a contiguous series of blocks. Note that the output disk 
contains an index file of the same size as the original disk. This is 
especially important when the contents of a large disk (such as an 
RP04) are restored to a smaller disk (such as an RK05) or vice versa. 

Compressing files in this manner is beneficial when retrieval pointers 
for a noncontiguous file header are almost used up. Because DSC 
creates each retrieval pointer to map as many contiguous blocks as 
possible (maximum is 256.), the number of pointers may be 
significantly reduced. DSC can also reduce the number of file 
extensions and extension headers. 
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Note that when DSC writes to a disk, it begins writing data into the 
lowest LBN possible. Free blocks generally have higher LB Ns and are 
in a contiguous section of the disk. 

The data presently on the disk is overwritten by the new data. 
Therefore, you cannot use DSC to transfer the contents of several 
small disks to a single large disk. Each copy operation eliminates 
whatever previously occupied the disk. 

In summary, to transfer data to a disk, DSC: 

1. Verifies that the disk is on line. 

2. Verifies that the disk has an up-to-date bad block descriptor 
or that bad blocks are specified manually (through the 
/BAD=NOA UTO switch) . Displays a warning message if no bad 
block information is available and the /BAD switch was not 
specified . 

3. Verifies that the disk has enough free blocks to contain all 
the data to be transferred. 

4. Creates index and directory files (in the first part of the 
disk) . 

5. Writes the data from a buffer. 



8. 10 DSC MESSAGES 

DSC notifies you of fatal error conditions as well as less serious 
conditions that could cause difficulties in DSC operations. Each 
message generated by DSC has the prefix DSC — , and each is identified 
by a numeric code. 

DSC messages are displayed on your terminal in either a long or a 
short form: on-line DSC displays the long form and stand-alone DSC 
displays the short form. You can determine the meaning of the short 
form message from the number provided with the message. Use the 
number to find the long form message in Section 8.10.1. The text 
accompanying the long form message of that number explains the error. 

For example, specifying a tape in the wrong format generates the 
following message in long form from DSC: 

FATAL *** 17 OUTPUT TAPE MM1: NOT ANSI FORMAT 

The same error generates the following message in short form on 
stand-alone DSC: 

FATAL *** 17 - MM1 

Error messages which only appear with the stand-alone versions of DSC 
are described in Section 8.10.3. 

Table 8-7 is a quick reference to the single letter codes used in 
general messages and in I/O messages (Section 8.10.2). 
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Table 8-7 

General Error and I/O Error Message Codes 



Type of 
Code 


Symbol 


Meaning 


General 


Code A 


Failed to read storage bit map header 


Error 


Code B 


Input data out of phase 


Message 


Code C 


Nondata block encountered 




Code D 


Input file out of phase 




Code E 


File attributes out of phase 




Code F 


File header out of phase 


I/O 


A 


Reading index file bit map 


Error 


B 


Reading index file header 


Message 


c 


Reading storage bit map 




D 


Reading boot or home block 




E 


Reading file header 




c 

r 


Input (or output device) 




G 


Writing index file bit map 




H 


Writing storage bit map header 




I 


Reading data 




J 


Reading input tape labels 




K 


Reading file attributes 




L 


Reading file header 




M 


Reading index file data 




N 


Reading summary data 







Writing file header 



When DSC identifies a file in which a problem has been detected, it 
provides only the file-ID (file number, file sequence number) of that 
file. Use the Dump utility (DMP) (described in Chapter 11) with the 
/FI switch and /HD switch to obtain the name of the file and other 
information contained in the file header. For example: 

DMP>TI: =devid :/FI : x :y/HD/BL: 

This command line will cause DMP to output to a terminal the header (s) 
of file x, y. The variables x and y, displayed in certain DSC error 
messages, represent the file number and file sequence number 
respectively. 



8.10.1 DSC General Messages 

The following are the general messages DSC can return. 



2 CONFLICTING DEV. TYPES 

Explanation: An illegal combination of device types was 
specified . 

User Action: Check for typographical errors in device 
abbreviations and make sure that the disks and tape drives are 
not specified on the same side of the command line. 
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MIXED TAPE TYPES 

Explanation: Two different types of tape drives were 
specified in the command line. 

User Action: Reenter the command line, specifying only one 
type of tape drive. 



ILLEGAL SWITCH 

Explanation: The command line was entered with a switch that 
cannot be used with that command line. 

User Action: Reenter the command line, specifying only 
correct switches. 



FILE LABEL TOO LONG 

Explanation: A file label consisting of more than 12(10) 
alphanumeric characters was specified. 

User Action: Reenter the command line, specifying a shorter 
file label. 



SYNTAX ERROR 

Explanation: An error occurred in the command line format. 
User Action: Reenter the command, specifying the right order. 



DUP. DEV. NAME; 

Explanation: The same device was entered more than once in 
the command line. 

User Action: Reenter the command line, specifying each device 
only once. 



TOO MANY DEV'S 

Explanation: More than the legal number of devices were 
specified on one side of the command line. 

User Action: Reenter the command line, specifying no more 
than eight devices per side. 



DEV. ddnn: NOT IN SYSTEM 

Explanation: The specified device is not present in the 
configuration of the operating system being used. 

User Action: Check the device identifier that was entered in 
the command line. Reenter the command line. 
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10 DEV. ddnn: NOT FILES-11 

Explanation: The specified input device is not formatted as a 
Files-11 device. 

User Action: Check the input device that was entered in the 
command line. Reenter the command line. 



11 BAD BLOCK SYNTAX ERROR 

Explanation: A syntax error occurred when bad block data was 
manually entered. 

User Action: Check the command line that was entered. 
Reenter it. 



12 BAD BLOCK COUNT TOO LARGE 

Explanation: There are too many groups of bad blocks (Maximum 
is 125.) on the output disk for DSC to handle. 

User Action: Use a different output disk. 



13 BAD BLOCK CLUSTER OUT OF RANGE 

Explanation: A manually entered bad block or group of bad 
blocks does not exist on the output disk. 

User Action: Check the numbers of the blocks entered. 
Reenter the command line. 



15 OUTPUT TAPE ddnn: FULL 

Explanation: The specified tape is full and files cannot be 
appended to it. 

User Action: Change the output tape. Reenter a command line 
to begin a new tape set. 



16 OUTPUT TAPE ddnn: NOT ONLY REEL IN SET 

Explanation: The /Append switch was used with a tape that was 
not the first tape of a set created by DSC. 

User Action: Change tapes. Reenter the command line (see 
message 15) . 



17 TAPE ddnn: NOT ANSI FORMAT 

OUTPUT TAPE 

Explanation: If the medium is an output tape, the /Append 
switch was specified and the tape is not in ANSI format. 

User Action: Reenter the command line and either omit the /AP 
switch to write the specified tape or change to an ANSI tape. 
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INPUT TAPE 

Explanation: If the medium is an input tape, the tape is not 
in the correct format for a DSC operation (that is, the tape 
was not created by DSC) . 

User Action: Check the tape and change it, if necessary. 
Reenter the command line. 



18 OUTPUT TAPE ddnn: NOT DSC TAPE 

Explanation: An /Append switch was specified with a tape that 
was not created by DSC. 

User Action: Reenter the command line and either omit the 
/Append switch or change to a DSC-created tape. 



19 TAPE ddnn: A CONTINUATION TAPE 

Explanation: If the medium is an input tape, the tape was 
mounted out of sequence and is not the first of a set. 

User Action: Reenter the command line and specify input tapes 
in the proper order. 



21 FAILED TO FIND HOME BLOCK 

Explanation: DSC failed to find the home block on the input 
disk. Either the disk is bad, the home block is bad, or the 
disk is not in Files-11 format. 

User Action: Check the disk in question, change drives if 
possible, and reenter the command line. 



22 FILE STRUCTURE LEVEL ON ddnn: NOT SUPPORTED 

Explanation: The device is not a Files-11 Structure Level 
disk, so it cannot be used. 

User Action: Replace the device, and reenter the command 
1 ine . 



23 I/O ERROR A ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the index 
file bit map on the device could not be read. 

User Action: If possible, correct the cause of the error. 
Reenter the command line. 



24 I/O ERROR B ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the index 
file header on the device could not be read. The specified 
file is lost. 

User Action: If possible, correct the cause of the error on 
the device. Reenter the command line. 
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25 CODE A 

Explanation: The. file header for the storage bit map file 
cannot be read. 

User Action: The disk is unusable and, therefore, cannot be 
copied. Replace the disk and reenter the command line. 



26 I/O ERROR C ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains the error that 
occurred when DSC read the specified file. 

User Action: Reenter the command line. 



27 I/O ERROR D ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains the read error 
that occurred when DSC read the home or boot block of the 
disk. 

User Action: Reenter the command line, specifying a new 
drive . 



31 I/O ERROR E ON ddnn: file ID 

... (Additional error information) 

Explanation: The I/O error indicated explains why the 
specified file header could not be read. 

User Action: If possible, correct the cause of the error. 
Reenter the command line. 



32 INPUT DEVICE ddnn: file ID, y, y NOT PRESENT 

Explanation: The specified file does not have a file header 
in the index file. The file is not copied. 

User Action: This is a warning only. If desired, the 
operation can be retried on a different drive. 



33 INPUT DEVICE ddnn: File ID y, y IS DELETED 

Explanation: The specified file was partially deleted on the 
input disk and was not copied. 

User Action: This is a warning only. No action is required. 



34 INPUT DEVICE ddnn: File ID y, y UNSUPPORTED STRUCTURE LEVEL 

Explanation: The header of the file indicated by the message 
does not contain 000401 in its File Structure Level Field 
(indicates ODS-1 structure) . DSC only copies ODS-1 files, 
therefore this file will not be copied. 

User Action: This message is only a warning. DSC will 
attempt to copy the remainder of the input. 



8-33 



DISK SAVE AND COMPRESS (DSC) 

35 INPUT DEVICE ddnn : File ID y, y FILE NUMBER CHECK 

Explanation: An incorrect file header was read from the disk, 
causing the specified file to be lost. 

User Action: Reenter the command line. 

36 INPUT DEVICE ddnn: File ID, y, y FILE HEADER CHECKSUM ERROR 

Explanation: Incorrect file header contents caused the 
specified file to be lost. 

User Action: Reenter the command line. 

37 INPUT DEVICE ddnn: File ID y, y SEQUENCE NUMBER CHECK 
Explanation: The sequence number is incorrect. 

User Action: Replace the disk and reenter the command line. 

38 INPUT DEVICE ddnn: File ID y, y SEGMENT NUMBER CHECK 

Explanation: The linkage connecting file segments was broken; 
the specified file is lost. 

User Action: Reenter the command line. 

39 DIRECTIVE ERROR error number 

Explanation: An internal error occurred, usually the result 
of a system overload. 

User Action: Reenter the command line. 

40 I/O ERROR F 

... (Additional error information) 

Explanation: The I/O error indicated explains that an 
uncorrectable read/write error occurred on the specified input 
or output device. 

User Action: This message is a warning only. No action is 
required unless another error message is displayed. If 
another error message is displayed, correct the cause of the 
error and reenter the command line. 

41 I/O ERROR I on ddnn: 
File ID y, y VBN z, z 

... (Additional error information) 

Explanation: An I/O error occurred that resulted in bad data 
being read from the specified virtual block number of the 
indicated file on the indicated device. 

User Action: This is a warning message only. You should 
examine the block specified to determine the extent of the 
error . 
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42 VERIFICATION ERROR ON ddnn: 

File ID y, y, y VBN z, z 

Explanation: The input and output devices specified for a 
verification operation did not match. 

User Action: This is a warning message only. No User Action 
is necessary. 



43 BAD DATA BLOCK ON ddnn: 

FILE ID, y, y, y VBN z, z 

Explanation: A parity error occurred when DSC copied the 
contents of a block from a disk. The block specified on the 
output disk contains erroneous data. 

User Action: When the copy operation is completed, the data 
contained in the specified block should be examined and 
corrected . 



44 MOUNT REEL x ON ddnn: AND HIT RETURN 

Explanation: This is an instruction only. 

User Action: Mount the volume number requested on the 
specified tape drive and press the RETURN key when ready. 



45 STARTING VERIFY PASS 

Explanation: The copy operation is complete and DSC is 
beginning the verify operation (specified with the /Verify 
switch) . 

User Action: This is an informational message only. No 
User Action is required. 



46 RESUME COPYING 

Explanation: The verify operation (specified with the /Verify 
switch) is complete and DSC is continuing the copy operation 
(if there is more material to copy). 

User Action: This is an informational message only. No 
User Action is required. 



47 ddnn: IS WRITE LOCKED. INSERT WRITE RING AND HIT RETURN. 

Explanation: The indicated device is wr ite-locked . 

User Action: Make sure the device is the one you want, 
write-enable it, and press the RETURN key. Reenter the 
command line. 
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48 INPUT FILE ON ddnn: WILL BE RESYNCHRONIZ ED 

Explanation: The tape position was lost while DSC was reading 
the input tape. The file specified in the message, as well as 
some subsequent files, may be lost. DSC may display 
additional error messages. 

User Action: Reenter the command line. 



49 OUTPUT DEVICE ddnn: FULL 

FILE ID y, y, y 

Explanation: The specified device cannot accommodate the 
indicated contiguous file in a contiguous set of blocks. This 
may mean that there is an inconsistency in the input tapes. 

User Action: Reenter the command line, specifying a less 
fragmented output disk. 



50 OUTPUT FILE HEADER FULL ON ddnn: x, FILE ID y, y, y 

Explanation: Too many bad blocks on the output disk have 
caused the generation of more retrieval pointers than can be 
stored in the current header (s) of the file. The allocation 
of blocks to the current output header is aborted. DSC will 
copy as many blocks as it has mapped to that header before it 
continues to allocate blocks to the header of the next output 
file. Note that some blocks will not be copied during this 
operation . 

User Action: After DSC completes the copy operation, use PIP 
to delete the unusable file on the output volume and to copy 
the file from the input volume to the output volume. 

PIP will assign a different file number to the output, other 
than the original input file number, therefore the files will 
not compare when you use the DSC /Compare switch. 



51 OUTPUT FILE HEADER ON ddnn: NOT MAPPED - FILE ID y, y, y 

Explanation: Space for the specified file header was not 
allocated. The file is lost. 

User Action: Reenter the command line; a new disk may be 
requi red . 



52 I/O ERROR G ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the Index 
File Bitmap could not be written. 

User Action: Reenter the command line. 
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53 FAILED TO READ FILE EXTENSION HEADER ON ddnn: FILE ID y, y, y 

Explanation: When copying from the input disk, DSC searched 

for an extension header, but did not find one. The remainder 

of the specified file was lost. A problem may exist with the 

input disk or a preceding I/O error may have caused an 
inconsistency. 

User Action: Reenter the command line. 



54 FAILED TO ALLOCATE HOME BLOCK 

Explanation: The home block cannot be created on the 
specified disk device because it has too many bad blocks. 

User Action: Replace the disk then reenter the command line. 



55 INDEX FILE ALLOCATION FAILURE 

Explanation: Too many bad blocks exist to allow the 
allocation for the specified file. 

User Action: Replace the disk, then reenter the command line. 



56 OUTPUT DISK ddnn: IS NOT BOOTABLE 

Explanation: Logical block number 0, which is the bootstrap 
block, of the specified disk or tape is bad. (This message 
will always be proceeded by message 84 and/or 86 indicating 
the reason for the error.) 

User Action: This is a warning only. No action is required. 



57 INVALID BAD BLOCK DATA 

Explanation: The bad block data on the output disk is 
inval id . 

User Action: Run the BAD program on the disk and manually 
enter bad block data or reenter the command line specifying 
another disk. 



58 BAD BLOCK FILE FULL 

Explanation: Too many bad blocks exist on the output disk. 
User Action: Replace the disk then reenter the command line. 



59 NO BAD BLOCK DATA FOUND 

Explanation: No bad block data exists for the specified 
output disk. 

User Action: If bad block data is not desired, ignore the 
message. Otherwise, run the BAD program on the disk; 
manually enter bad block data; or reenter the command line, 
specifying a new disk. 
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6 OUTPUT DEVICE ddnn: IS A DIAGNOSTIC PACK. DO NOT USE IT! 

Explanation: The specified output disk is a diagnostic pack 
and cannot be used. 

User Action: Mount a new output disk and reenter the command 
1 ine . 



61 CODE B ON ddnn: 

File ID y, y, y VBN z, z 

Explanation: The tape position was lost when DSC read the 
virtual block number specified. Some data may be lost. 

User Action: Determine the extent of the error. If 
necessary, try the tape on another drive or create another 
tape. 



62 CODE C ON ddnn: 

File ID y, y, y VBN z, z 

Explanation: The tape position was lost when DSC read the 
data file specified. Data beyond the VBN mentioned is lost. 

User Action: Re-create the tape or reenter the command line 
specifying a different tape drive. 



6 3 CODE D ON ddnn: 

File ID y, y, y EXPECTED p, p, p FOUND y 

Explanation: The tape position was lost while DSC read the 
tape specified in the message. All of H y, y, y" and some of 
"Pr Pr P" are lost. 

User Action: Reenter the command line. 



64 FAILED TO MAP OUTPUT FILE ON ddnn: 

File ID p, p, p VBN z, z 

Explanation: An inconsistency occurred when DSC was writing 
the specified file to output disk. The file header did not 
specify the correct number of virtual blocks required to write 
the file and the file is lost. 

User Action: Reenter the command line. 



65 OUTPUT DISK ddnn: IS TOO SMALL — nn BLOCKS NEEDED 

Explanation: The output disk is not large enough to 
accommodate the data to be transferred. 

User Action: Reenter the command line, specifying a larger 
output disk. 
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66 I/O ERROR C ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the storage 
bit map could not be read. 

User Action: Reenter the command line. 



67 I/O ERROR H ON ddnn: 

Explanation: The message that follows explains why the header 
of the storage bit map file could not be written. 

User Action: Reenter the command line. 



68 I/O ERROR J ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the tape 
labels on the specified device could not be read. 

User Action: Reenter the command line, specifying a different 
tape drive. 



69 INPUT TAPE ON ddnn: MUST BE AT BOT 

Explanation: The specified tape must be at Beginning of Tape 
(BOT). This message is also displayed during a verify 
operation to indicate that the current volume is rewinding to 
enable the verify operation. 

User Action: If the /Verify switch was not specified, check 
the tape and remount at BOT. 



7 WRONG INPUT TAPE ON ddnn: 

EXPECTING File ID, FOUND File ID 

Explanation: The input tapes were specified out of sequence. 

User Action: Check the tapes, then reenter them in proper 
order after receiving the mount instructions. 



71 CODE E ON ddnn: AFTER File ID y, y, y 

Explanation: This message is the result of a read error from 
tape. When trying to read an attribute block, DSC accessed 
some other block. The file following the file specified in 
the error message is lost. 

User Action: Reenter the command line. 
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I/O ERROR K ON ddnn : 

AFTER File ID y, y, y 

... (Additional error information) 

Explanation: The I/O error indicated explains why the 
attributes of the specified file could not be read. 

User Action: Reenter the command line. 



I/O ERROR L ON ddnn: 

AFTER File ID y, y, y 

... (Additional error information) 

Explanation: The message that follows explains the I/O error 
that occurred while DSC was reading the file header from tape. 

User Action: Reenter the command line. 



INPUT TAPE ddnn: RESYNCHRONIZ ED AT File ID y, y, y 

Explanation: The tape position has been recovered. Some data 
preceding the file specified was lost. 

This message is usually received with one or more error 
messages, all indicating that the input tape was either read 
incorrectly or recorded badly. 

User Action: The tape should be re-created and the operation 
reinitiated . 



TAPE FILE filelabel NOT FOUND 

Explanation: The input tape specified does not contain Lhe 
file identified as "filelabel." 

User Action: Check the file label and the tape, then reenter 
the command specifying the correct tape and file label. 



EXPECTED EXTENSION HEADER NOT PRESENT ON ddnn: File ID y, y, y 

Explanation: A required file extension header could not be 
found on the tape being read. 

User Action: If the error message was preceded by one or more 
I/O warning messages. Reenter the command line. If not, the 
input tape is bad and should be regenerated. 



CODE F ON ddnn: AFTER File ID y, y, y 

Explanation: This is the result of a read error from tape. 
When trying to read a file header, DSC accessed some other 
block type. The file following the file specified in the 
error message is lost. 

User Action: Reenter the command line. 
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78 I/O ERROR M ON ddnn: 

... (Additional error information) 

Explanation: The message following the device name explains 
why the Index File data could not be read. 

User Action: Reenter the command line. 



79 INDEX FILE DATA NOT PRESENT 

Explanation: When reading the input tape, DSC accessed a file 
other than the index file. This message is the result of a 
tape error or an I/O error. 

User Action: Re-create the tape or retry the same tape on a 
different tape drive. 



8 I/O ERROR N ON ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the index 
and storage bitmap files from the specified input tape could 
not be restored. 

User Action: Reenter the command line, specifying a different 
input tape drive. 



81 VOLUME SUMMARY DATA NOT PRESENT 

Explanation: Either DSC did not create the input tape or the 
tape contains incomplete data. 

User Action: Check the tape and reenter the command line. 



82 I/O ERROR ON ddnn: - File ID y, y, y 

... (Additional error information) 

Explanation: The I/O error indicated explains why the 
specified file header could not be written. 

User Action: Reenter the command line. 



8 3 BAD BLOCKING FACTOR 

Explanation: The specified blocking factor is too large for 
the current operating system. 

User Action: Specify a smaller blocking factor and reenter 
the command line. 



8 4 INPUT DISK NOT BOOTABLE 

Explanation: The input disk does not have a valid boot block, 
therefore the output disk will not be bootable. This message 
will always be accompanied with message 56 stating that the 
output disk will not be bootable. 

User Action: This is a warning only. No action is required. 
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85 INPUT/OUTPUT DISKS DIFFER 

Explanation: The boot block is usually different for each 
disk type, therefore the output disk may not have a valid boot 
block and may not be bootable. (This message will always be 
accompanied by other messages pertaining to the bootability of 
the output disk.) 

User Action: This is a warning only. If message 84 is also 
displayed, a copy from the output disk to another disk that is 
the same type as the original input disk will yield a disk 
that is bootable. 



86 BAD LBN # 

Explanation: The output disk has a bad LBN which is the 
boot block; therefore, the output disk will not be bootable. 

User Action: This is a warning only. A copy from the output 
disk to another disk with a good LBN will yield a disk that 
is bootable. 



87 OUTPUT DISK ddnn: MAY NOT BE BOOTABLE 

Explanation: This message is always preceeded by message 85 
which indicates the reason for the error. Other messages 
concerning the bootability of the output disk may proceed this 
message. (If message 56 is displayed, the output disk will 
not be bootable. 

User Action: Refer to message 56 and messages 84, 85, and 86 
for more detail. 



8.10.2 DSC I/O Messages 

In on-line and both stand-alone versions of DSC, I/O errors are 
identified by one or more of the following messages which explain the 
type of I/O error that occurred. 

BAD BLOCK NUMBER 

Explanation: The block does not exist on the disk; an 
internal DSC error has occurred. 

BAD BLOCK ON DEVICE 

Explanation: A bad area was encountered on the device, 
resulting in a block that cannot be read or written without 
error . 

BLOCK CHECK OR CRC CHECK 

Explanation: A parity error occurred indicating that bad data 
may have been transferred. 

User Action: Reenter the command line. 
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DATA OVERRUN 

Explanation: A physical block on tape contains more bytes 
than were requested. 

DEVICE NOT READY 

Explanation: The device is not ready or not up to speed. 
DEVICE OFFLINE 

Explanation: The device is not in the system. 

User Action: Check the device and the device specification in 
the command line, then reenter the command line. 

DEVICE WRITE LOCKED 

Explanation: The disk drive is wr ite-locked . 

User Action: Write-enable the disk drive and reenter the 
command line. 

END OF FILE DETECTED 

Explanation: The tape position was lost. 

User Action: Reenter the command line. 
END OF TAPE DETECTED 

Explanation: The tape position was lost. 

User Action: Reenter the command line. 
END OF VOLUME DETECTED 

Explanation: The tape position was lost. 

User Action: Reenter the command line. 
FATAL HARDWARE ERROR 

Explanation: A hardware malfunction occurred. 

User Action: Reenter the command line. If the error repeats, 
call your DIGITAL Field Service representative. 

HANDLER NOT RESIDENT 

Explanation: The device driver (handler) was not loaded. 

User Action: Load the appropriate device driver and reenter 
the command line. 

INSUFFICIENT POOL SPACE 

Explanation: The operating system is overloaded. 

User Action: Reenter the command line. 
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PARITY ERROR ON DEVICE 



Explanation : 



An uncorrectable read error occurred. 



User Action: 



Reenter the command line. 



PRIVILEGE VIOLATION 



Explanation: A device was mounted as Files-11 or is allocated 
to a different user. 

User Action: 

RSX-11M Users: Dismount the disk, allocate the device to 
yourself, and reenter the command line. 

RSX-11M-PLUS Users: Dismount the disk, mount it as a foreign 
device and reenter the command line. 



Explanation: An I/O error that DSC cannot translate occurred. 

User Action: If possible, translate the error code and 
reenter the command line. 



Explanation: Tapes on drives have not been rewound since the 
system was booted. 

User Action: Rewind the tapes, using the /Rewind switch in a 
DSC command line. 



8.10.3 Stand-Alone DSC Messages 

The following messages appear only with the stand-alone version 
DSCSYS.SYS. (Similar messages are generated by DSC64K. SYS if you 
specify invalid values.) 

ILLEGAL VECTOR ADDRESS 



Explanation: An illegal vector address was specified. 

User Action: Correct the vector specification and reenter the 
command line. Vector addresses must be a multiple of 4 and 
less than or equal to 374(8). 



Explanation: A system trap occurred when the specified CSR 
address was referenced. 

User Action: Correct the address and reenter the command 
line . 



ERROR CODE IS <Driver code> 



ILLEGAL 



FUNCTION 



INVALID CSR ADDRESS 
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INVALID TM02 ASSIGNMENT 



Explanation: The /TM02 switch applies only to TU16/TE16/TU45 
tapes and cannot specify an assignment greater than seven. 

User Action: Correct the error and reenter the command line. 

SPECIFIED UNIT NUMBER EXCEEDS MAX. OF 1 

Explanation: Stand-alone DSC does not accept unit numbers 
greater than 1. 

User Action: Correct the error and reenter the command line. 
Specify the /Unit switch if required. 
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CHAPTER 9 

PILE STRUCTURE VERIFICATION UTILITY (VFY) 



The File Structure Verification Utility (VFY) for Files-11 volumes 
provides the ability to: 

• Check the readability and validity of a file-structured volume 
(default function) . 

• Print the number of available blocks on a file-structured 
volume (/FR). 

• Search for files in the index file that are not in any 
directory; that is, files that are "lost" in the sense that 
they cannot be accessed by file name (/LO). (See the 
IAS/RSX-11 I/O Operations Reference Manual for a description 
of the index file.) 

• Validate directories against the files they list (/DV). 

• List all files in the index file, showing the file ID, file 
name, and owner (/LI). 

• Mark as "used" all the blocks that appear to be available but 
are actually allocated to a file (/UP). 

• Rebuild the storage allocation bitmap so that it properly 
reflects the information in the index file (/RE) . 

• Restore files that are marked for deletion (/DE). 

• Delete bad file headers (/HD). 

• Perform a read check on every allocated block on a 
file-structured volume (/RC) . 

The volume to be verified must be mounted as a Files-11 device. 

There should be no other activity on the volume while VFY is 
executing. In particular, activities that create new files, extend 
existing files, or delete files should not be attempted while VFY is 
executing a function. 

VFY must not be aborted while a /UP, /RE, /DE, or /HD switch is being 
processed. Aborting VFY while it is modifying the storage allocation 
or index files can seriously endanger the integrity of that volume. 
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9 . 1 VFY COMMAND FORMAT 

The command line for VFY uses the format: 
VFY>listf ile,scr ate hdev=indev/s witch 
The parameters of this command format are: 
Output Parameters 
listf ile 

Specifies the output listing file in the following format: 

dev: [ufd] f i lename . f il etype ; ver 

If you do not specify a device, the default for the output 
listing device is the issuing terminal (TI:). The [ufd] is the 
UIC under which VFY is currently running. You must, however, 
specify the file name and file type of the output file. The 
default version number will be the latest version plus one. 

scratchdev 

Specifies the device on which the scratch file produced by VFY is 
to be written. This parameter is in the following format: 

dev : 

The scratch file is used by VFY during the verification scan and 
during the lost file scan. It is created but not entered in a 
directory. Therefore, it is transparent to you. The scratch 
file is automatically deleted when VFY is terminated. If you do 
not specify a scratch device the default device is SYO:. 

If the user's default system disk is faulty or full, use this 
parameter to direct the scratch file to another device. The 
scratch file should always be assigned to a volume other than the 
indev volume. The scratch file is not used with the /FR and /LI 
swi tches . 

Input Parameters 

indev 

Specifies the volume to be verified in the format dev:. If you 
do not specify the volume, the default is SYO:. 

/switch 

Specifies the function to be performed by VFY. 

The VFY switches are described in detail in Section 9.4. 



9-2 



FILE STRUCTURE VERIFICATION UTILITY (VFY) 



9.2 VFY MODE OF OPERATION 

VFY normally operates in read-only mode, where the scratch file, if 
required, is on another device. VFY requires write access under the 
following conditions: 

1. If the /UP or /RE switch is used, VFY requires write access 
to the storage allocation map ( [0, 0]BITMAP. SYS ) . 

2. If the /DE or /HD switch is specified, VFY requires write 
access to the index file ( [0, 0] INDEXF. SYS ) . 

3. If the /LO switch is specified and lost files are found, VFY 
requires write access to the [1,3] User File Directory which 
is the directory containing "lost" files. 

If write access to the volume index or bitmap files is required for 
the desired operation, the user must mount the volume using the 
/UNLOCK switch with the MCR or DCL MOUNT command. 

VFY may be run under any UIC if only read access is required. If 
write access is required, VFY must run under a system UIC. 



9.3 VFY VALIDITY CHECK 

VFY checks the readability and validity of the volume mounted on the 
specified device. This function is the default function and entails 
reading all the file headers in the index file and ensuring that all 
the disk blocks referenced in the map area of each file header are 
allocated to that file in the volume bitmap. 

The volume may be wr ite-protected if it is not the system volume, or 
if the required scratch file is directed to another file-structured 
volume . 

A validity check is specified in the following format: 
1 istf ile,scratchdev=indev<RET> 
or 

indev<RET> 
Example 

>VFY DRO: 

CONSISTENCY CHECK OF INDEX AND BITMAP ON DRO: 



INDEX INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680. 
BITMAP INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680. 



9 . 4 VFY SWITCHES 

VFY functions are specified with switches appended to the VFY command 
line. The switches and their functions are summarized in Table 9-1. 
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Table 9-1 
VFY Switches and Functions 



Switch 


Format 


Description 


Delete 


/DE 


Resets the marked-for-delete 
indicators . 


Directory Validation 


/DV 


Validates directories against 
the files they list. 


Free 


/FR 


Prints out the available space 
on a volume. 


Header Delete 


/HD 


Deletes bad file headers on a 
volume. The subswitch /AL 
allows the /HD switch to 
delete bad file headers 
without prompting the user. 


Identify 


/ID 


Identifies the VFY version. 
This switch may be specified 
on a command line by itself at 
any time. 


List 


/LI 


Lists the index file by file 
ID. 


Lost 


/LO 


Scans the file structure 
looking for files which are 
not in any directory. 


Read Check 


/RC 


Checks the volume to see if 
every block of every file can 
be read. 


Rebuild 


/RE 


Recovers blocks that appear to 
be allocated but are not 
contained in a file. 


Update 


/UP 


Allocates blocks that appear 
to be available but have been 
allocated to a file. 



9.4.1 Delete Switch (/DE) 

The Delete switch (/DE) resets the marked-for-delete indicators in the 
file header area of files that were marked for deletion but never 
deleted . 

VFY must be running under a system UIC and the volume must be mounted 
with the /UNLOCK switch. 
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9.4.2 Directory Validation Switch (/DV) 

The Directory Validation Switch (/DV) examines each directory on the 
volume. (VFY considers any file on the volume with the file type .DIR 
and a fixed record length of 16 bytes to be a directory.) It then 
reports any errors found that could be attributed to a corrupt 
directory or a nonexistent file listed in the directory. For example: 

>VFY DX:/DV 

THE FOLLOWING DIRECTORY ENTRIES WERE INVALID 

[301,333] FILE ID 13,2,0 DELETED. FIL; 1 - FILE NOT FOUND 

[301,333] FILE ID 12345,3,0 CORRUPTED. FID; 1 - FILE NOT FOUND 

[301,333] FILE ID 14,2,0 GARBAGE . VER ; 123456 - INVALID VERSION NUMBER 

[301,333] FILE ID 15,1,444 RELVOLNEZ . ERO; 1 - RESERVED FIELD WAS NON-ZERO 

4. INVALID DIRECTORY ENTRIES WERE FOUND 

Directory entries may be invalid due to the following conditions: 

FILE NOT FOUND 

The file was either deleted without the corresponding directory 
entry being removed or the file ID field in the directory entry 
was corrupted. If the file does exist, it cannot be accessed 
with this directory entry. 

Remove the directory entry using the PIP /RM command. 

INVALID VERSION NUMBER 

The directory entry was corrupted. If the file does exist, it 
cannot be accessed with this directory entry. 

Remove version zero of the file with the PIP /RM command. 

RESERVED FIELD WAS NON-ZERO 

The third word of the file ID field in a directory entry is a 
reserved field and should always be zero. Remove the directory 
entry with PIP /RM and then reenter it with the PIP /EN command. 



9.4.3 Free Switch (/FR) 

The Free switch (/FR) displays the available space on a specified 
volume with the following message: 

dev: HAS nnnn. BLOCKS FREE, nnnn. BLOCKS USED OUT OF nnnn. 



9.4.4 Header Delete Switch (/HD) 

The Header Delete switch (/HD) recognizes all bad file headers on a 
volume. If you specify the /AL subswitch, all bad file headers will 
automatically be deleted. 
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If you do not specify the /AL subswitch, VFY prompts you as follows: 



>VFY DX1:/HD 



CONSISTENCY CHECK OF INDEX AND BITMAP ON DX1: 

FILE ID 000015,000003 007334. DIR;1 OWNER [7,334] 

BAD FILE HEADER 
DELETE THIS HEADER [Y/N/Q/G ] ? 



You may respond as follows: 



Y (RET) deletes the header and proceeds 

N (RE?) does not delete the header and proceeds 

Q (ret) does not delete the header and does not proceed 

G (ret) deletes the header and all subsequent bad headers 

(ret) does not delete the header and proceeds 



If you give any other response, the following message will appear: 



VFY — ILLEGAL RESPONSE - TRY AGAIN 



9.4.5 List Switch (/LI) 

The List switch (/LI) lists the index file. The output for each file 
specifies the file number, file sequence number, file name, and owner 
UIC, as shown in the following example: 



VFY>DK:/LI 

LISTING OF INDEX ON DK0: 



FILE 


ID 


000001 


, 000001 


INDEXF.SYS 


;l 


OWNER 


[1,1] 


FILE 


ID 


000002 


, 000002 


BITMAP. SYS 


;i 


OWNER 


[1,1] 


FILE 


ID 


000003 


, 000003 


BADBLK. SYS 


;l 


OWNER 


[1,1] 


FILE 


ID 


000004 


, 000004 


000000. DIR 


;i 


OWNER 


[1,1] 


FILE 


ID 


000005 


, 000005 


COR IMG. SYS 


;i 


OWNER 


[1,1] 


FILE 


ID 


000006 


, 000006 


001001. DIR 


;l 


OWNER 


[1,1] 


FILE 


ID 


000007 


, 000007 


001002. DIR 


;i 


OWNER 


[1,2] 


FILE 


ID 


000010 


, 000010 


EXEMC.MLB ;1 


OWNER 


[1,1] 


FILE 


ID 


000011 


, 000011 


RSXMAC.SML 


;i 


OWNER 


[1,1] 


FILE 


ID 


000012 


, 000012 


NODES. TBL ; 


l 


OWNER 


[1,1] 


FILE 


ID 


000013 


, 000036 


QIOSYM.MSG;311 


OWNER 


[1,2] 


FILE 


ID 


000014 


, 000037 


F4PCOM .MSG 


;l 


OWNER 


[1,2] 



9.4.6 Lost Switch (/LO) 

The Lost switch (/LO) scans the file structure looking for files that 
are not in any directory and cannot be referenced by file name. (VFY 
considers any file on the volume with the filetype .DIR and a fixed 
record length of 16 bytes to be a directory.) A list of the files is 
produced, and if the "lost file directory" [1,3] exists on that 
volume, the files will be entered in that directory. If an I/O error 
occurs, however, on a directory file operation, the files will not be 
entered into [1,3]. The following error message will appear: 

FAILED TO OPEN DIRECTORY FILE 

ERROR CODE -16. - DIRECTORY [301, 333] 

AS A RESULT, NO FILES WILL BE ENTERED IN [1,3] 
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9.4.7 Read Check Switch (/RC) 

The Read Check switch (/RC) checks to ensure that every block of every 
file on a specified volume can be read. 

The optional parameter [:n] is the blocking factor that indicates the 
number of file blocks to be read at a time. The default value is the 
maximum number of blocks available in VFY's buffer area. The buffer 
area available may be increased by installing VFY in a larger 
partition. Four blocks are available when VFY is installed in an 8K 
partition, and four blocks are added for each IK increment. 

For the fastest read check, the maximum block factor should be used. 
Whenever an error is encountered, each block of the portion in error 
is reread to determine which data block (s) cannot be read. 

When an error is detected, a file identification line is displayed in 
the following format: 

FILE ID nn,nn filename. typ;ver . n blocks used/n blocks allocated 

Following this line, an error message is displayed. If a blocking 
factor other than 1 is in use, an error message in the following form 
will be issued: 

ERROR STARTING AT VBN nl,n2 LBN nl,n2 - ERROR CODE -n 

Following the first error message, there should be one or more error 
messages indicating the exact block(s) in error. The second error 
message line(s) will be in the following form: 

ERROR AT VBN nl,n2 LBN nl,n2 - ERROR CODE -n 

If an ERROR STARTING AT line is displayed without one or more ERROR AT 
lines, a multiblock read operation on the selected device has failed, 
but the data blocks appear to be individually readable. 

If the VBN of the unreadable block listed in the ERROR AT line is 
beyond the block-used-count, the data portion of the file is readable. 

The negative number printed after the ERROR CODE message is usually -4 
to indicate a device parity error. Other error codes are contained in 
the IAS/RSX-11 I/O Operations Reference Manual . 



9.4.8 Rebuild Switch (/RE) 

The Rebuild switch (/RE) recovers lost blocks; that is, blocks that 
appear to be allocated but are not contained in any file. 

Multiply-allocated blocks must be deleted from the file structure 
before the Rebuild switch can take effect. 

You must run VFY under a system UIC and write-enable the volume. The 
scratch file should be on another volume. 
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9.4.9 Update Switch (/UP) 

The Update switch (/UP) allocates blocks that appear to be available 
but are actually allocated to a file. 

Files with multiply-allocated blocks must be deleted from the file 
structure before the Update switch can take effect. 

You must run VFY under a system UIC and write-enable the volume. The 
scratch file should be on another volume. 



9.5 FILE ERROR REPORTING 

As VFY verifies a volume, error conditions are reported. Errors for a 
given file are preceded by a line that identifies the file in error. 
This line is formatted as follows: 

FILE ID nn,mm filename. f iletype ; version OWNER [uic] 

nn , mm 

Represents the unique file identification number assigned to the 
file by the system at file-creation time. 

filename 

Represents the file name. 

•f iletype 

Represents the file type (for example, .OBJ for object file). 
; version 

Represents the version number of the file. 

[uic] 

Represents the UIC for the file. 

This file identification line is followed by one or more of the 
following messages: 

I/O ERROR READING FILE HEADER-ERROR CODE -32 

Explanation: VFY failed to read the file header for the 
specified file ID. The device is not mounted or is off-line, or 
the hardware has failed. 

BAD FILE HEADER 

Explanation: VFY checks on the validity of the file header 
indicate that the header has been corrupted. 

MULTIPLE ALLOCATION n,m 

Explanation: The specified (double-precision) logical block 
number is allocated to more than one file. If this error occurs, 
a second pass is automatically taken which will indicate all 
files that share each multiply-allocated block. The second pass 
is taken after all file headers have been checked (see Section 
9.5. 2) . 
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BLOCK IS MARKED FREE n,m 

Explanation: The specified logical block number is allocated to 
the indicated file but is not marked as allocated in the storage 
allocation map (see Section 9.5.4). 

BAD BLOCK NUMBER n,m 

Explanation: The specified block number was found in the header 
for this file but is illegal for the device (out of range) . This 
indicates a corrupted file header. 

FILE IS MARKED FOR DELETE 

Explanation: A system failure occurred while the specified file 
was being deleted. The deletion was not completed and the file 
header still exists (see Section 9.5.1). 

HEADER MAP ERROR 

Explanation: VFY detected an error in the header map area that 
also indicates a corrupted file header. 



The last error message for the file is followed by a summary line for 
that file, as follows: 

SUMMARY: MULT=nn, FREE=nn , BAD=nn. 

MULT 

Specifies the number of multiple block allocations. 



FREE 



BAD 



Specifies the number of blocks marked free that should have been 
allocated . 



Specifies the number of errors encountered in the the map area of 
the file header. 

If the output for VFY is directed to a terminal and you do not wish to 
see the error messages for a given file, enter CTRL/0. This 
terminates the listing of error messages for that file that is, all 
messages but the summary line. 



9.5.1 Files Marked-for-Delete 

If a file has been marked for delete but the deletion process was not 
completed, you can either restore the file, if you still need it, or 
you can delete the file to recover the space it was occupying. This 
situation only occurs when the system crashes during file processing. 
Once files have been restored or deleted, run VFY with the /RE switch 
to assure the consistency of the volume's storage allocation bitmap. 
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9.5.1.1 Restoring a File Marked-for-Delete - To restore a file 
marked-for-delete , mount the disk volume using the MCR or DCL MOUNT 
command and the /UNLOCK switch. For example: 

>MOU DKO-./UNL 

Then, run VFY specifying the /DE switch to reset the marked-for-delete 
indicators in file headers. Once the delete indicator has been reset, 
run VFY specifying the /LO switch to scan the entire file structure. 

The deletion process may have proceeded partially and a portion at the 
end of the file may be missing. This condition can be detected by a 
directory listing obtained using the PIP /FU command. 



9.5.1.2 Deleting a File Marked-for-Delete - Files that are 
marked-for-delete can be deleted directly with PIP, once their unique 
file ID has been obtained by doing a validity check. The file ID 
appears as the first entry in the file identification line that 
precedes each list of file errors (see Section 9.5). The following 
example shows how the file ID is used with PIP to delete a file: 

>PIP /FI: 12: 20/DE 

In this example, the file with file ID 12,20 is deleted from the 
system device. PIP issues the error message: 

PIP — FAILED TO MARK FILE FOR DELETE-NO SUCH FILE 

since the file system denies the existence of files already 
marked-for-delete; however, the file is deleted. 



9.5.2 Deletion of Bad File Headers 

If the volume contains bad file headers, it is advisable to delete 
them first by using the /HD switch before you address the problem of 
multiply-allocated or free blocks. Deleting bad file headers may free 
the blocks that were contained in the files with the bad headers. See 
Section 9.4.4 for a description of the /HD switch. 



9.5.3 Deletion of Multiply-Allocated Blocks 

If the file structure contains multiply-allocated blocks, it is 
necessary to delete files until there are no such blocks. An 
automatic rescan of the volume identifies which files share which 
blocks. This rescan lists the files which contain the 
multiply-allocated blocks. Use this information to determine which, 
if any, of the files can be saved and then delete the rest with the 
PIP delete function. 

After the files have been deleted, VFY should be run once again to 
ensure that all of the files containing multiply-allocated blocks have 
been deleted. 
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9.5.4 Elimination of Free Blocks 

Once there are no multiply-allocated blocks, the next concern is the 
elimination of blocks that are marked as free in the storage 
allocation bitmap but are actually allocated to a file. To reallocate 
these blocks in the storage allocation bitmap, run the validity check 
with the /UP switch. This allocates all blocks that should have been 
marked as allocated. See Section 9.4.9 for a description of the /UP 
switch. 

When you have no multiply-allocated blocks and no blocks marked as 
free that are actually in use, the file structure is safe for writing 
new files and extending existing files. Files may have data blocks 
that have been overwritten as the result of multiple allocation. 



9.5.5 Recovering Lost Blocks 

To determine whether any blocks have been lost on a file-structured 
volume, examine the last two lines of output from the Validity Check 
(Section 9.3). The last two lines of output give the free space on 
the volume. The first line reports the amount of available space 
according to the index file (that is, the number of blocks that are 
not in use by any file in the index file) . The second line reports 
the amount of available space according to the storage allocation 
bitmap. 

If there are no errors, these two figures should agree. If the index 
file indicates that more blocks are free than the storage allocation 
bitmap indicate, then those blocks are "lost" in the sense that they 
appear to be allocated, but no file contains them. Lost blocks can be 
recovered by rerunning the Validity Check and specifying the /RE 
switch. See Section 9.4.8 for a description of the /RE switch. 



9 . 6 VFY ERROR MESSAGES 

The VFY error messages, their explanations, and suggested user actions 
are described below. 

VFY — COMMAND SYNTAX ERROR 

Explanation: The command as entered does not conform to command 
syntax rules. 

User Action: Reenter the command line with the correct syntax 
specified . 



VFY — CLOSE FAILURE ON BIT MAP 
or 



VFY — CLOSE FAILURE ON INDEX FILE 
or 

VFY — CLOSE FAILURE ON TEMPORARY FILE 
or 
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VFY — CLOSE FAILURE ON LISTING FILE 
or 

VFY — I/O ERROR ON INPUT FILE 
or 

VFY — I/O ERROR ON OUTPUT FILE 
or 

VFY — I/O ERROR READING DIRECTORY FILE 
or 

VFY — I/O ERROR WRITING FILE HEADER 
or 

VFY — FAILED TO CLOSE DIRECTORY FILE 

Explanation: One of the following conditions may exist: 

• The device is not on-line. 

• The device is not mounted. 

• The hardware has failed. 

User Action: Determine which of the above conditions caused the 
message and correct that condition. Reenter the command line. 

VFY — FAILED TO ALLOCATE SPACE FOR TEMP FILE 

Explanation: The volume specified for the temporary scratch file 
is full. 

User Action: Use PIP to delete unnecessary files and rerun VFY, 
or specify another volume as the scratch device when you reenter 
the command line. 

VFY — FAILED TO ATTACH DEVICE 
or 

VFY — FAILED TO DETACH DEVICE 

Explanation: The list file specified a terminal device. VFY was 
not able to attach or detach the device. 

User Action: Reenter the command line with a list file device 
that can be attached or detached. 
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VFY — FAILED TO ENTER FILE 

Explanation: One of the following conditions may exist: 

• VFY is not running under a system UIC. 

• The device is not on-line. 

• The device is not mounted. 

• The hardware has failed. 

User Action: Determine which of the conditions caused the 
message and correct that condition. Reenter the command line. 

VFY — FAILED TO FIND INDEXF.SYS;1 IN MFD - WILL OPEN INDEX BY FILE ID 1,1 
or 

VFY — FAILED TO FIND BITMAP. SYS; 1 IN MFD - WILL OPEN BITMAP BY FILE ID 2.2 

Explanation: The Master File Directory has been corrupted. 

User Action: Copy the disk using the BRU utility (see Chapter 
7). 

VFY — FAILED TO OPEN DIRECTORY FILE (See OPEN FAILURE error messages) 

VFY — ILLEGAL DEVICE 

Explanation: The input device specified is something other than 
a disk or DECtape. 

User Action: Reenter the command line with a mounted Files-11 
device specified. 

VFY — ILLEGAL SWITCH 

Explanation: The switch specified is not a valid VFY switch or a 
valid switch is used illegally. 

User Action: Reenter the command line with the correct switch 
specified . 

VFY — NO DYNAMIC MEMORY AVAILABLE - PARTITION TOO SMALL 

Explanation: VFY does not have enough buffer space to run. 
User Action: Run VFY in a larger partition (8K minimum) . 

VFY — OPEN FAILURE ON BIT MAP 
or 

VFY — OPEN FAILURE ON INDEX FILE 
or 
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VFY — OPEN FAILURE ON LISTING FILE 
or 

VFY — OPEN FAILURE ON TEMPORARY FILE 
or 

VFY — FAILED TO OPEN DIRECTORY FILE 
or 

VFY — FAILED TO OPEN FILE FOR READ CHECK 

Explanation: One of the following conditions may exist: 

VFY is not running under a system UIC but should be. 

The named file does not exist in the specified directory. 

The volume is not mounted. 

The specified file is read protected. 

The specified file does not exist. 

User Action: Determine which of the above conditions caused the 
message and correct that condition. Reenter the command line. 

VFY — STORAGE CONTROL BLOCK (VBN1 of BITMAP. SYS) IS CORRUPTED 

Explanation: The Storage Control Block is corrupt. This is 
harmless, because only VFY and PIP /FR can examine the block. 

User Action: Copy the disk using BRU or DSC (see Chapter 7 or 8, 
respectively) . 



VFY — THEY ARE STILL LOST, COULD NOT FIND DIRECTORY 

Explanation: UFD [1,3] did not exist on the volume. UFD [1,3] 
is the "lost files" directory. VFY enters all files found by the 
/LO switch into this directory. 

User Action: Use the MCR UFD command to enter UFD [1,3] on the 
volume . 
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CHAPTER 10 
LIBRARIAN UTILITY PROGRAM (LBR) 



The Librarian Utility Program (LBR) allows you to create, update, 
modify, list, and maintain library files. A library file is a direct 
access file that contains a collection of related files. LBR 
organizes files, usually having the same file type, into library 
modules so that you have rapid and convenient access to your files. 

Library files contain two directory tables: the entry point table 
(EPT) and the module name table (MNT) . The EPT contains entry point 
names that consist of global symbols defined as entry points in MACRO 
source programs. The MNT contains names of the modules in the 
library. Both tables are alphabetically ordered. 

The following paragraphs describe the three types of libraries: 
object, macro, and universal. 

Object library files ( . OLB) contain object files (.OBJ). The module 
names are derived from .TITLE directives, while the entry point names 
are derived from global symbols defined in the module. LBR references 
the module code in the library by the module name. The source program 
references object library modules by the entry point name. Entry 
points apply only to object libraries. 

You use object module libraries as input to the Task Builder. The 
Task Builder (TKB) searches for definitions of all global symbols 
referenced in a program in the following manner. First, TKB searches 
the other modules specified, then it searches the specified 
user-written object module library, and finally, it searches the 
system library. 

Macro library files (.MLB) contain source macro files (.MAC). The 
module names are derived from .MACRO directives. From each macro 
definition, LBR extracts the name and creates an entry in the module 
name table. The entry in the module name table is the means by which 
the assembler finds the associated macro definition in the library. 

You use macro library modules as input to the MACRO-11 Assembler. The 
assembler searches the specified library for macros listed in .MCALL 
statements and called in the source program before searching the 
system macro library. 

Universal library files (.ULB) contain modules inserted from any kind 
of file whether it be a program or text. The module names are either 
user-specified in the Insert (/IN) switch or derived from the file 
name at the time of insertion. 

Primarily, you use universal libraries to package related files 
together. You can reference a universal library module in a program 
by using the Universal Library Access ($ULA) system library routine. 
$ULA, specified in the macro source program, establishes the necessary 
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conditions for access (read only) to a universal library module. (For 
more information on $ULA, see the IAS/RSX- 11 System Library Rou ti ne s 
Reference Manual . ) 

You can invoke LBR using any of the methods for invoking a utility 
described in Chapter 1. 



10.1 FORMAT OF LIBRARY FILES 

A library file consists of a library header, an entry point table, a 
module name table, the library modules and their headers, and any 
available space. The entry point table has zero length for macro and 
universal libraries. Figure 10-1 illustrates object and macro library 
file format and Figure 10-2 illustrates universal library file format. 



10.1.1 Library Header 

The header section is a full block in which the first 24(10) words are 
used to describe the current status of the library. The header's 
contents are updated as the library is modified. This allows LBR to 
access the necessary information to perform its functions (for 
example, Insert, Compress, and Delete). The twenty-fourth word in the 
library header is the default insert file type for universal libraries 
and is undefined for macro and object libraries. See Figure 10-3. 



10.1.2 Entry Point Table 

The entry point table consists of 4-word elements containing an entry 
point name (words 0-1) and a pointer to the module header of the 
module where the entry point is defined (words 2-3). (See Figure 
10-4.) This table is searched when a library module is referenced by 
one of its entry points. The table is sequenced in order of ascending 
entry point names. The entry point table applies only to object 
library files. 



10.1.3 Module Name Table 

The module name table is searched when the library module is 
referenced by its module name rather than by one of its entry points. 
It is made up of 4-word elements: a module name (words 0-1) and a 
pointer to the module header (words 2-3). See Figure 10-5. The 
module name table is sequenced in order of ascending module names. 



10.1.4 Module Header 

Each module starts with a header of eight words for object and macro 
modules and 32(10) words for universal modules. The module header 
contains information about the module such as the type and status of 
the module, its length (number of words), and its attributes. See 
Figure 10-6 and Figure 10-7. 

In object and universal modules, the low-order bit of the attributes 
byte is set if the module has the selective search attribute. In 
universal modules, bit 1 of the attributes byte is set if the input 
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file was contiguous. Also, in object modules, the two words of 
type-dependent information contain the module identification defined 
by the .IDENT directive at assembly time. In macro modules, these two 
words are undefined. 

For universal modules, type-dependent identification is derived from 
the file type and version number of the input file. 

Universal libraries allow you to change the module header, which 
contains optional descriptive information, by means of the Modify 
Header switch (/MH) . 



FIXED- 
LENGTH 
RECORDS 



VARIABLE - 

LENGTH 

RECORDS 



LIBRARY 
HEADER 



ENTRY POINT 
TABLE 



MODULE NAME 
TABLE 



MODULE 1 HEADER 



MODULE 1 



MODULE N HEADER 



MODULE N 



AVAILABLE SPACE 



BLOCK 

BOUNDARIES 



Figure 10-1 General Format for Object and Macro Library Files 
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FIXED- 
LENGTH 
RECORDS 



VARIABLE- 

LENGTH 

RECORDS 



LIBRARY 
HEADER 



ENTRY POINT 
TABLE 



MODULE NAME 
TABLE 



MODULE 1 HEADER 
UNUSED SPACE 

MODULE 1 



BLOCK 
BOUNDARIES 



UNUSED SPACE 



MODULE 2 HEADER 
UNUSED SPACE 



MODULE 2 



UNUSED SPACE 



MODULE N HEADER 
UNUSED SPACE 



MODULE N 



AVAILABLE SPACE 



NOTE 

All universal module headers and the 
first record of each universal module 
will start on a block boundary. 

ZK-1 85-81 



Figure 10-2 Universal Library File Format 
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OFFSET 



WORD 


NON ZERO ID 


LIBRARY TYPE 


2 


LBR (LIBRARIAN) 


VERSION 


4 


( . IDENT FORMAT) 


6 


YEAR 


10 


DATE AND 


MONTH 


12 


TIME LAST 


DAY 


14 


INSERT 


HOUR 


16 


MINUTE 


20 


SECOND 


22 


RESERVED 


SIZE EPT ENTR'S 


24 


EPT STARTING RELATIVE BLOCK 


26 


NO. EPT ENTRIES ALLOCATED 


30 


NO. EPT ENTRIES AVAILABLE 


32 


RESERVED 


SIZE MNT ENTR'S 


34 


MNT STARTING REL BLOCK 


36 


NO. MNT ENTRIES ALLOCATED 


40 


NO. MNT ENTRIES AVAILABLE 


42 


LOGICALLY DELETED 


44 


AVAILABLE (BYTES) 


46 


CONTIGUOUS 


SPACE 


50 


AVAILABLE (BYTES) 


52 


NEXT INSERT RELATIVE BLOCK 


54 


START BYTE WITHIN BLOCK 


56 


UNIVERSAL DEFAULT INSERT TYPE 1 



-^-UNDEFINED FOR MACRO AND OBJECT LIBRARIES 

ZK- 186-81 

Figure 10-3 Contents of Library Header 
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WORD 



GLOBAL SYMBOL 




NAME 


(RAD50) 


ADDRESS 


OF 


RELATIVE BLK. 


MODULE 










HEADER 




BYTE IN BLOCK 



Figure 10-4 Format of Entry Point Table Element 



WORD 



MODULE NAME 




(RAD50) 




ADDRESS 


OF 


RELATIVE BLK. 


MODULE 










HEADER 




BYTE IN BLOCK 



Figure 10-5 Format of Module Name Table Element 



OFFSET FROM 

START OF 
MODULE HEADER 





2 
4 
6 
10 
12 
14 
16 



ATTRIBUTES 



STATUS 



SIZE OF 



MODULE (BYTES) 



DATE 

MODULE 

INSERTED 



TYPE DEPENDENT 
INFORMATION 



YEAR 



MONTH 



DAY 



0=NORMAL MODULE 
1=DELETED MODULE 



Figure 10-6 Module Header Format for Object and Macro Libraries 
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OFFSET FROM 
START OF 
MODULE HEADER 



10 
12 
14 
16 
20 
22 
24 
26 
30 
32 
34 
36 

40 

42 
44 

76 



ATTRIBUTES 



STATUS 



SIZE OF 



MODULE (BYTES) 



DATE 



MODULE 



INSERTED 



IDENT 



OPTIONAL 



INFO 



OPTIONAL 



INFO 



OPTIONAL 



INFO 



OPTIONAL 



INFO 



USER 
FILE 

ATTRIBUTES 



YEAR 



MONTH 



DAY 



ZK-1 90-81 



Figure 10-7 Module Header Format for Universal Libraries 
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10.2 LBR RESTRICTIONS 

The following restrictions apply when using LBR: 

• Limit of 65, 536 (64. K) words per module. 

• Limit of 65, 536 (64. K) blocks per library. 

• Tables should be allocated their anticipated maximum size. 
Expanding table allocations requires using the Compress switch 
(/CO) to copy the entire file. 

• A fatal error results if an attempt is made to insert a module 
into a library that contains a module with a different name 
from, but with the same entry point as, the inserted module. 
For further information, refer to the discussion of the /IN 
switch in Section 10.5.8. 

• The use of wildcards in file specifiers is not allowed (that 
is, forms such as *.OBJ, where the * indicates all modules 
with type .OBJ) . 

The library's tables must contain enough space for both the modules 
being replaced and their replacements because the new modules are 
entered and the old modules are only logically (not physically) 
deleted . 



10.3 LBR COMMAND LINE 

LBR accepts command lines in the following general format: 

outfile[,listfile]=infilel[,infile2,...infilen] 

LBR allows only one level of indirect command file nesting. For a 
complete description of file specifiers, see Chapter 1. 



10.4 DEFAULTS FOR LBR FILE SPECIFIERS 

Table 10-1 describes the defaults for LBR file specifiers. 



Table 10-1 
LBR File Specifiers Defaults 



Specifier 


Default 


dev : 


Output File 
SY0: 

Listing File 

The device that was specified for the output 
file; otherwise, the default for the output 
file. 

Input File 

For the first input file specifier, SY0:. 

For subsequent input file specifiers, the 
device specified in the previous input file 
specifier; otherwise, the default for the 
previous input file specifier. 



(continued on next page) 
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Table 10-1 (Cont.) 
LBR File Specifiers Defaults 



Specifier 



Default 



dev : 



filename 
.type 



;ver 



/switch 



Output File [ufd] Output File 

The UIC under which LBR is currently running. 

Listing File 

The UFD that was specified for the output 
file; otherwise, the default for the output 
file specifier. 



Input File 

For the first input file specifier, the 
under which LBR is currently running. 



UIC 



For subsequent input file specifiers, the UFD 
specified in the previous input file 
specifier; otherwise, the default for the 
previous input file specifier. 

No default. Must be specified. 

Output File 

Depends on the default in effect (see Section 
10.5.4), except when the Compress (/CO) or 
Create (/CR) switch is specified (see 
Sections 10.5.1 and 10.5.2, respectively). 

Listing File 
. LST 

Input File 

Refer to the descriptions of Compress 
(Section 10.5.1), Insert (Section 10.5.8), 
and Replace (Section 10.5.11) switches. 

Latest version of the file, or latest version plus 1 
for the output file when the Compress (/CO), Create 
(/CR), or Extract (/EX) switches are specified. 



Output File 

/IN (Insert) 

List File 

/SP/LI (Spool and List module names) 

Input File 

None . 



10. 5 LBR SWITCHES 

LBR uses switches appended to file specifications to invoke functions. 
These switches are summarized in Table 10-2. 
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Table 10-2 
LBR Switches 



Option 


Switch 


Function 


Compress 


/CO 


Compress a library file. 


Create 


/CR 


Create a library file. 


Delete 


/DE 


Delete a library module and all of its 
entry points. 


Default 


/DF 


Specify the default library file type. 


Delete ulODdl 


/no 


"1 r> 4- £\ "1 t K k 3 v \ / m /"\ 1 1 "1 Q onf ru HA 1 n f 
UclcLc a 1 lui a I y raouuic ciiUL y puxiiu. 


Entry Point 


/EP 


Include entry point elements in the 
library entry point table. 




/-EP 


Exclude entry point elements in the 

1 ihrarv pnhrv o<*> l'nt' f" 3 h 1 p . 

X 1UL uL y CI 1 U 1 J IT uQU J. C • 


I-j A LL L 


/FX 


Pvhrant / rpaH \ nnp nr mnrp modul ps from 

ua Li L \ L ~ Q\Ji J Wile wi. Ill UL C -L CO J_ l. will 

a library file and write them into a 
specified output file. 


Insert 


/IN 


Insert a module. 


Ltl Si 


/r t 


LI bu IuOQUie naluco • 




/T F 


IjI o L III <J U u _L tr lid 111 dl 1U III (J U U J. t: ell L t y 

points . 




/FU 


List module names and full module 


Mod i f v Hpadpr 


/MH 


Modify 3 universal rnodul© hGador* 


r\e ^ij. clL c 


/Dp 


Pan! a/^o A m /"> H ill o 




/-RP 


Do not replace a module. 


Spool 


/SP 


Spool the listing for printing. 




/-SP 


Do not spool the listing. 


Selective Search 


/ss 


Set the selective search attribute in 
the module header. 


Squeeze 


/sz 


Reduce the size of the macro source. 




/-sz 


Do not reduce the size of a specific 
macro source. 



10.5.1 Compress Switch (/CO) 

Use the Compress switch (/CO) to physically delete all logically 
deleted records, to put all free space at the end of the file, and to 
make the free space available for new library module inserts. 
Additionally, the library table specification may be altered for the 
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resulting library. LBR accomplishes this by creating a new file that 
is a compressed copy of the old library file. The old library file is 
not deleted after the new file is created. 

The /CO switch can be appended only to the output file specification. 
The format for specifying the /CO switch is: 

outf ile/CO:size :ept :mnt=inf ile 

outfile 

Specifies the file that is to become the compressed version of 
the input file. The default file type is . OLB if the input file 
is an object library, .MLB if the input file is a macro library, 
or . ULB if the input file is a universal library. 

/CO 

Specifies the Compress switch. 

:size 

Specifies the size of the new library file in 256(10)-word 
blocks. The size of the old library file is the default size. 

:ept 

Specifies the number of entry point table (EPT) entries to 
allocate. If the value specified is not a multiple of 64(10), 
the next highest multiple of 64(10) is used. The number of EPTs 
in the old library file is the default value. This parameter is 
always forced to zero for macro libraries and universal 
libraries. The maximum number of entries is 4096(10). 

:mnt 

Specifies the number of module name table (MNT) entries to 
allocate. If the value specified is not a multiple of 64(10), 
the next highest multiple of 64(10) is used. The number of MNTs 
in the old library file is the default value. The maximum number 
of entries is 4096(10). 

infile 

Specifies the library file to be compressed. The default file 
type is .OLB for object libraries, .MLB for macro libraries, and 
.ULB for universal libraries. The actual default file type is 
determined by the current default library file type (see Section 
10. 5. 4) . 

Example 

LBR>RICKLIB/CO: 100. :128. : 64. =SHEILA. OLB 

In this example, file SHEILA. OLB is compressed, and a new file, 
RICKLIB . OLB , is created with the following attributes: 

size = 100(10) blocks 

ept = 128(10) entry points 

mnt = 64(10) module names 

The new file, RICKLIB. OLB, receives a version number that is one 
version greater than the latest version for the file. 
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Both files, RICKLIB . OLB and SHEILA. OLB, reside in the default 
directory file on SYO:. 



10.5.2 Create Switch (/CR) 

Use the Create switch (/CR) to allocate a contiguous library file on a 
direct access device (for example, a disk). The switch initializes 
the library file header, the entry point table, and the module name 
table . 

The /CR switch can be appended only to the output file specification. 
The format for specifying the /CR switch is: 

outf ile/CR: size :ept :mnt :1 ibtype=inf iletype 

outf ile 

Specifies the library file being created. The default file type 
is .OLB if an object library is being created, .MLB if a macro 
library is being created, or .ULB if a universal library is being 
created . 

/CR 

Specifies the Create switch. 

:size 

Specifies the size of the new library file in disk (256 (10) word) 
blocks. The default size is 100(10) blocks. 

:ept 

Specifies the number of entry point table (EPT) entries to 
allocate. The default value is 512(10) for object libraries. 
This parameter is always forced to zero for macro libraries and 
universal libraries. The maximum number of entries is 4096(10). 

:mnt 

Specifies the number of module name table (MNT) entries to 
allocate. The default value is 256(10). The maximum number of 
entries is 4096 (10) . 

: libtype 

Specifies the type of library to be created. Acceptable values 
are OBJ for object libraries, MAC for macro libraries, and UNI 
for universal libraries. The default is the last value specified 
or implied with the /DF switch (see Section 10.5.4), or OBJ if 
/DF has not been specified. 

: inf iletype 

Specifies the default input file type for the created universal 
library. If this value is not specified, the default input file 
type for universal libraries is .UNI. This value is not defined 
for object or macro libraries. 

If the values specified for ept and mnt are not multiples of 64(10), 
EPT and MNT are automatically filled out to the next disk block 
boundary. 
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Example 

LBR>RICKLIB/CR: : 128. :64. :OBJ=SHEILA, LAURA, JENNY 

In this example, a combination of functions is performed. First, 
the library file RICKLIB.OLB is created in the default directory 
on SYO:. RICKLIB has the following attributes: 

size = 100(10) blocks (default size) 
ept = 128(10) entry points 
mnt = 64(10) module names 
type = .OBJ 

Secondly, object modules from the input files SHEILA. OBJ, 
LAURA. OBJ, and JENNY. OBJ, which reside in the default directory 
on SYO:, are inserted into the newly created library file. 
Insert (/IN) is the default switch for input files (see Section 
10, 5. 8) . 



10.5.3 Delete Switch (/DE) 

Use the Delete switch (/DE) to logically delete library modules and 
their associated entry points (global symbols) from a library file. 
Up to 15(10) library modules and their associated entry points can be 
deleted with one delete command. 

When LBR begins processing the /DE switch, it prints the following 
message on the initiating terminal: 

MODULES DELETED: 

As modules are logically deleted from the library file, the module 
name is printed on the initiating terminal. (See the example at the 
end of this section.) 

If a specified library module is not contained in the library file, a 
message is printed on the initiating terminal and the processing of 
the current command is terminated. This message is as follows: 

LBR — *FATAL*-NO MODULE NAMED "name" 

The /DE switch can be appended only to the library file specification. 

When LBR deletes a module from a library file, the module is not 
physically removed from the file, but is marked for deletion. This 
means that, although the module is no longer accessible, the file 
space that the module once occupied is not available for use (unless 
the deleted module is the last module that was inserted) . To 
physically remove the module from the file and make the freed space 
available for use, you must compress the library (see Section 10.5.1). 

The format for specifying the /DE switch is: 

outf ile/DE: module 1 [: module 2. . . :modulen] 
outf ile 

Specifies the library file. 

/DE 

Specifies the Delete switch. 
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: module 

Specifies the name of the module to be deleted. 
Example 

LBR>R ICKLIB/DE : SHE ILA : LAURA : JENNY 

MODULES DELETED: 

SHEILA 

LAURA 

JENNY 

In this example, the modules SHEILA, LAURA, and JENNY and their 
associated entry points are deleted from the latest version of 
library file SYO: RICKLIB. OLB. 



10.5.4 Default Switch (/DF) 

Use the Default switch (/DF) to specify the default library file type. 
Acceptable default values are OBJ for object libraries, MAC for macro 
libraries, and UNI for universal libraries. When a default library 
file type is not specified by the /DF switch, OBJ is the default 
library file type. 

Specifying a default value: 

1. Sets the default file type for the Create switch (/CR). 

2. Provides a file type default value of .MLB for macro 
libraries, . ULB for universal libraries, and .OLB for object 
libraries when opening an output (library) file. Exceptions 
to this occur when you use /CO or /CR. When you specify /CO, 
the default applies to the library input file. When you 
specify /CR, the default file type is .OLB if an object 
library is being created, .ULB if a universal library is 
being created, or .MLB if a macro library is being created. 

The /DF switch only affects the filetype of the file to be 
opened. After that, the library header record information is 
used to determine the type of library file being processed. 

The /DF switch can be issued alone or appended to a library file 
specification. The format for specifying the /DF switch is: 

outf ile/DF: filetype . . . 

or 

/DF: filetype 
outf ile 

Specifies the library file. 

/DF 

Specifies the Default switch. 
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f iletype 

Specifies the default library file type: OBJ for object library 
files, MAC for macro library files, and UNI for universal library 
files. 

If a value other than OBJ, ULB, or MAC is specified, the current 
default library type will be set to object libraries and the 
following message will be displayed: 

LBR — * FA TAL*-IN VALID LIBRARY TYPE SPECIFIED 

Examples 

LBR>/DF:MAC 
LBR>RICKLIB=inf ile 

The file RICKLIB .MLB is opened for insertion. 
LBR>/DF:MAC 

LBR>RICKLIB/DF:OBJ=inf ile 

OBJ replaces MAC as the default f iletype. The file RICKLIB. OLB 
is opened for insertion. 

LBR>/DF:MAC 
LBR>RICKLIB/CR 

The macro library RICKLIB. MLB is created. 

LB R>/DF : MAC 
LBR>RICKLIB/CR: : : : OBJ 

Because OBJ is specified, it overrides the default (MAC). The 
object library RICKLIB. OLB is created. 

LBR>/DF : OBJ 

LBR>TEMP/CO=RICKL IB .MLB 

Because RICKLIB. MLB is a macro library, MAC overrides the default 
(OBJ). The macro library file TEMP. MLB is created to receive the 
compressed output. 

LBR>/DF: UNI 
LBR>RICHLIB=TEST 

The file RICHLIB . ULB is opened for insertion. 



10.5.5 Delete Global Switch (/DG) 

Use the Delete Global switch (/DG) to delete a specified entry point 
(global symbol) from the EPT. Up to 15(10) entry points may be 
deleted with one command. This command does not affect the object 
module that contains the actual symbol definition. You may wish to 
delete an entry point if a module to be inserted has the same entry 
point . 

When LBR begins processing the /DG switch, it prints the following 
message on the initiating terminal: 

ENTRY POINTS DELETED: 
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As entry points are deleted from the library file, the entry point is 
printed on the initiating terminal. (See the example at the end of 
this section.) 

If a specified entry point is not contained in the EPT, a message is 
printed on the initiating terminal and the processing of the current 
command is terminated. This message is as follows: 

LBR — * FATAL* - NO ENTRY POINT NAMED "name" 
The /DG switch can only be appended to the library file specification. 
The format for specifying the /DG switch is: 

outf ile/DG:globall [:global2. . . :globaln] 
outf lie 

Specifies the library file. 

/DG 

Specifies the Delete Global switch, 
global 

Specifies the name of the entry point to be deleted. 
Example 

LBR>RICKLIB/DG: SHEILA: LAURA: JENNY 

ENTRY POINTS DELETED: 

SHEILA 

LAURA 

JENNY 

In this example, the entry points SHEILA, LAURA, and JENNY are 
deleted from the latest version of the library file named 
SY0:RICKLIB.OLB. 



10.5.6 Entry Point Switch (/EP) 

Use the Entry Point switch (/EP) to control (include or exclude) the 
placement of global symbols in a library entry point table. The 
switch can be specified in either a positive or negative format: 

/EP Include entry points in the entry point table. 

/-EP Do not include entry points in the entry point table. 

/NOEP Do not include entry points in the entry point table. 

The positive format (/EP) causes all entry points in a module or 
modules to be entered in the library entry point table. 

Either negative format (/-EP or /NOEP) provides for a module to be 
included in a library, but excludes the entry points in that module 
from being entered in the library entry point table. 
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/EP is the LBR default. If the switch is not specified, all entry 
points are entered into the library entry point table. 

The /EP switch has no effect on macro or universal libraries. 

The format for specifying the /EP switch is: 

outfile[ /EP ]=inf ile, ... inf ilen 
[/-EP ] 
[/NOEP] 

or 

outf ile=inf ile[ /EP ][,... inf ilen [/EP ] 
[-/EP ] [-/EP] 
[/NOEP] [/NOEP] 

outf ile 

Specifies the output file. When the entry point switch is 
applied to this file specification, LBR assumes each of the input 
files contains modules for which entry points are to be either 
included or excluded. 

inf ile 

Specifies an input file. When the /EP switch is applied to an 
input file specification, LBR assumes only the input files to 
which the switch is applied contain modules for which entry 
points are to be either included or excluded. 



NOTE 

Although not reflected in the command 
formats, the positive and negative forms 
of the switch may be applied to both the 
output and input file specifications. 
For example, the effect of /EP applied 
to the output file can be overridden by 
applying /-EP to a specific input file. 



The /-EP switch is useful for including modules that contain duplicate 
entry point names in the same library. The /-EP switch provides the 
means for entering a module in the library without having its entry 
points included in the library entry point table. 

The /-EP switch is also useful in the case where the Task Builder uses 
only module names to search for modules in an object module library. 
In this case, entries in the library entry point table are not 
required. The /-EP switch can be used to exclude entry points from 
being entered in the library entry point table. 

Depending on whether the /EP switch is applied to the output 
specification or to an input specification, it has either a global or 
local effect. 

When applied to the output file specification, the /EP switch has a 
global effect. That is, LBR either includes all entry points in the 
entry point table or excludes all entry points from being entered in 
the entry point table. 
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When applied to an input file specification, the Entry Point switch 
has a local effect. That is, LBR either includes entry points in the 
entry point table or excludes entries from being entered in the entry 
point table for only those modules to which the switch is applied. 

Entry points in an object module are not affected by the /EP switch. 
The switch only affects entries in the library entry point table. 



10.5.7 Extract Switch (/EX) 

Use the Extract switch /EX to extract (read) one or more modules from 
an object or macro library file and write them into a specified output 
file. If more than one module is extracted, the modules are 
concatenated in the output file. The extract operation has no effect 
on the library file from which the modules are extracted; that file 
remains intact. Up to eight modules may be specified in one extract 
operation for object and macro libraries. However, only one module 
may be specified in one extract operation for a universal library. 

For object and macro libraries, if no modules are specified in the 
command line, all modules in the library are extracted and 
concatenated in the output file in alphabetical order. 

For universal libraries, RMS fields cannot be extracted to a 
record-oriented device, such as a terminal. 

The /EX switch may be applied only to input file specifications. The 
format for specifying the /EX switch is: 

outf il e=inf ile/EX [ :modulenamel. . . tmodulenamen] 

outf ile 

Specifies the file into which extracted modules are to be stored. 
The default file type for this file is .OBJ if the input modules 
are object modules. The default file type is .MAC if the input 
modules are macro modules. If the library is a universal 
library, the outfile retains the infile type of the module 
extracted. (However, you are allowed to extract only one 
universal library module at a time.) 

infile 

Specifies the library file from which the modules are to be 
extracted. The default file type for this file is .ULB, .OLB, or 
.MLB, depending on the current default library type. 

/EX 

Specifies the Extract switch, 
modulename 

Specifies the name of the module to be extracted from the 
1 ibrary . 

Examples 

LBR>DRIVERS=RSX11M/EX:DXDRV: DKDRV: TTDRV 

The object modules DXDRV, DKDRV, and TTDRV are concatenated in 
alphabetical order and written into the file DRIVERS. OBJ. 
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LB R>T I : = [ 1 , 1 ] RSXMAC . SM L/EX : QI $S 

The macro QIO$S is written to the issuing terminal. 
LBR>TEST. OBS=TEST/EX 

All of the modules in the library TEST. OLB are written into the 
file TEST.OBS in alphabetical order. 



10.5.8 Insert Switch (/IN) for Object and Macro Libraries 

Use the Insert switch /IN to insert modules into a library file. Any 
number of input files can be specified. For object libraries and 
macro libraries, each input file can contain any number of 
concatenated input modules. For macro libraries, only first-level 
macro definitions are extracted from the input files. All ^text 
outside of the first-level macro definitions is ignored. LBR 
recognizes only upper-case characters in macro directives. (The 
Insert switch for Universal Libraries, is explained in Section 
10.5.9.) The /IN switch is the default library file option and can be 
appended only to the library file specification. 

If you attempt to insert an input module that already exists in the 
library file, the following message is printed on the initiating 
terminal : 

LBR — * FATAL* DUPLICATE MODULE NAME "name" IN filename 

Likewise, if you attempt to insert a module and a module contains an 
entry point that duplicates one that is already in the EPT, the 
following message is printed on the initiating terminal: 

LBR — * FATAL* DUPLICATE ENTRY POINT "name" IN filename 
The format for specifying the /IN switch is: 

outf ile[/IN]=infilel[,inf ile2, . . .inf ilen] 
outf ile 

Specifies the library file into which the input modules are to be 
inserted. The default file type depends on the current default 
(see Section 10.5.4). It is .OLB if the current default is 
object libraries, .MLB if the current default is macro libraries. 

/IN 

Specifies the Insert switch, 
infile 

Specifies the input file containing the modules to be inserted 
into the library file. The default file type is .OBJ if the 
outfile is an object library and .MAC if the outfile is a macro 
1 ibrary . 
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Example 

LBR>RICKLIB/IN=SHEILA r LAURA, JENNY 

In this example, the modules contained in the latest versions of 
files SHEILA, LAURA, and JENNY, which reside in the default 
directory on SYO: , are inserted into the latest version of the 
library file RICKLIB, which also resides in the default directory 
on SYO:. The default file type for files SHEILA, LAURA, and 
JENNY is .OBJ if RICKLIB is an object module library, or .MAC if 
RICKLIB is a macro library. 



10.5.9 Insert Switch (/IN) for Universal Libraries 

The Insert switch (/IN) works basically the same for universal 
libraries as it does for object libraries and macro libraries. 
However, when inserting a file into a universal library, the /IN 
switch is applied to the input file rather than the output file. You 
can also specify module name and descriptive information as switch 
values in the command line. In addition, LBR copies input file 
attributes to the module header. 

The high block indicator (F.HIBK of the file's descriptor block) and 
the end of file indicator (F.EFBK of the file's FDB) are included in 
the input file's user file attributes. LBR makes the high block 
indicator equal to the end of file indicator in the module header. 
This means that when a module is extracted to a file, that file will 
have as many blocks allocated to it as are used. 

The format for specifying the /IN switch for universal libraries is: 

outf il e=inf ile/IN:name :op:op:op:op 
outf ile 

Specifies the universal library into which the infile is to be 
inserted . 

infile 

Specifies the input file to be inserted into the outfile. The 
default for the file type is the value indicated at the universal 
library's creation time. (See Section 10.5.2.) 

/IN 

Specifies the Insert switch. 

:name 

Optionally specifies the module name (up to six Radix-50 
characters) . The default is the first six characters of the 
input file name. 

:op 

Specifies optional descriptive information (up to six Radix-50 
characters) to be stored in the module header. The default is 
null. If only part of the information set is specified, all 
preceding colons must be supplied. 
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Example 

LBR>R ICKLIB . ULB = JOE. TXT/IN : MODI : THIS : IS : JAN2: TEXT 

In this example, LBR inserts JOE. TXT into the universal library 
RICKLIB . ULB as MODI. "THIS", "IS", "JAN2", and "TEXT" are stored 
in the module header. 

You can insert JOE. TXT without the /IN switch and its values. As 
a result, all the information normally specified by the switch 
values defaults as described in this example. 



10.5.10 List Switches (/LI, /LE, /FU) 

Use the list switches to produce a printed listing of the contents of 
a library file. Three switches allow you to select the type of 
listing desired. These switches are as follows: 

/LI Produces a listing of the names of all modules in the 

library file. 

/LE Produces a listing of the names of all modules in the 

library file and their corresponding entry points. 

/FU Produces a listing of the names of all modules in the 

library file and gives a full module description for 

each: that is, size, date of insertion, and 
module-dependent information. 

These switches can be appended only to the output file specification 
or the list file specification. 

The /LI switch is the default value. It need not be specified when a 
listing file has been specified or when any other list switch is 
included in the command line. 

The format for specifying list switches is: 

outfile[, list file] /switch (es) 

outf ile 

Specifies the library file whose contents are to be listed, 
listf ile 

Optionally specifies the listing file. If not specified, the 
listing is directed to the initiating terminal. 

/switch (es) 

Specifies the list option (s) selected. 
Examples 

LB R>RICKL IB/LI 

In this example, a listing of the names of all the modules 
contained in file SYO: RICKLIB. OLB is printed on the initiating 
terminal . 
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LBR>RICKLIB/LE 

In this example, a listing of the names of all the modules and 
their entry points (contained in file SYO:RICKLIB. OLB) is printed 
on the initiating terminal. 

LBR>RICKLIB/FU 

In this example, a listing of the names of all the modules in 
file SY0:RICKLIB.OLB, and a full description of each one 
contained is printed on the initiating terminal. 

LBR>DK1: [200, 200] RICKLIB , LP. LST/LE/FU 

In this example, LBR creates file LP.LST in directory [200,200] 
on DK1, which lists the module names, their entry points, and a 
full description of each module for file RICKLIB. 



10.5.11 Modify Header Switch (/MH) 

The Modify Header switch pertains only to universal libraries and 
allows you to modify the optional user-specified information in the 
module header. 

The format for specifying the /MH switch is: 

outf ile/MH: module :op:op:op:op 
outf ile 

Specifies an output file for the universal library. The file 
type defaults to . ULB . 

/MH 

Specifies the Modify Header switch. 
: module 

Specifies the name of the module whose descriptive information is 
to be modified. 

:op 

Specifies the optional user information (up to six Radix-50 
characters) to be stored in the module header. The default is 
null and indicates that the corresponding information field is 
not to be changed. Also, entering a pound sign (#) clears the 
corresponding information field. 

Example 

The optional descriptive information for module A of RICKLIB. ULB 
is : 

"MODA" " FCHCD" "OF" "FCH" 
The LBR command is: 
LBR>RICKLIB/MH: A: FCHTS : #: : 
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The optional descriptive information for module A in file RICKLIB 
is changed to: 

" FCHTS" " w "OF" w FCH n 



10.5.12 Replace Switch (/RP) For Macro and Object Libraries 

Use the Replace switch /RP to replace modules in a library file with 
input modules of the same name. Any number of input files are allowed 
and each file can contain any number of concatenated input modules. 

For macro libraries, only first-level macro definitions are extracted 
from the replacement files. LBR recognizes only uppercase characters 
in macro directives. 

When a match occurs on a module name, the existing module is logically 
deleted and all of its entries are removed from the EPT. 

As each module in the library file is replaced, a message is printed 
on the initiating terminal. This message, which contains the name of 
the module being replaced, is as follows: 

MODULE "name" REPLACED 

If the module to be replaced does not exist in the library file, LBR 
assumes that the input module is to be inserted and automatically 
inserts it without printing a message. 

The /RP switch can be specified in either of the following formats: 

• Global format - The /RP switch is appended to the library file 
specification and all of the input files are assumed to 
contain replacement modules. 

• Local format - The /RP switch is appended to an input file 
specification and only the file to which the /RP switch is 
appended is considered to contain replacement modules. 

Global Format 

outf ile/RP=inf ilel [,infile2,...infilen] 

outf ile 

Specifies the library file. The default file type depends on the 
current default (see Section 10.5.4). It is . OLB if the current 
default is object libraries or .MLB if the current default is 
macro libraries. 

/RP 

Specifies the Replace switch, 
inf ile 

Specifies the input file that contains replacement modules for 
the library file. The default type is .OBJ if outfile is an 
object library or .MAC if it is a macro library. 

The Global format allows you to specify a list of input files without 
having to append the /RP switch to each of them. 
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To override the global function for a particular input file (that is, 
to instruct LBR to process a particular file in a list as a file 
containing modules to be inserted but not replaced) , append /-RP or 
/NORP to the desired input file specification. 

Local Format 

outf ile=infilel[/RP] [ ,inf ile2 [/RP] , . . . inf ilen [/RP] ] 
outf ile 

Specifies the library file. The local format default is the same 
as the global format default. 

inf ile 

Specifies the input file that contains replacement modules for 
the output library file. The local format default is the same as 
the global format default. 

/RP 

Specifies the Replace switch. Appending the /RP switch to an 
input file specifier constitutes the local format of the switch. 
This overrides the LBR default (/IN) and instructs LBR to treat 
the module(s) contained in the specified file as replacement 
modules . 

Examples 

The files used in the following four examples, and the modules 
contained within each file, are depicted in Figure 10-8. These 
files are assumed to reside in the default directory on the 
default device and the initial state of the library file is 
assumed to be as shown in Figure 10-8. 

1. LBR>RICKLIB/RP=SHEI LA, LAURA, JENNY 

MODULE "SHEILA" REPLACED 
MODULE "LAURAl" REPLACED 
MODULE "LAURA2" REPLACED 
MODULE " JENNY1" REPLACED 
MODULE "JENNY2" REPLACED 

In this example, the global format for the /RP switch is 
used. Object modules from the input files SHEILA, LAURA, and 
JENNY replace modules by the same names in the library file 
named RICKLIB and modules JENNY3 and LAURA 3 are inserted. 
The resulting library file is shown in Figure 10-9. 

2. LBR>RICKLIB=CHRIS , SHE I LA/ RP 
MODULE "SHEILA" REPLACED 

In this example, the local format of the /RP switch is used. 
The object module SHEILA from file SHEILA is replaced in the 
library file RICKLIB. The object modules in the file CHRIS 
are inserted in the library file. (See the description of 
the /IN switch in Section 10.5.8.) The resulting library file 
is shown in Figure 10-10. 
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3. LBR>RICKLIB/RP=SHEILA, LAURA, JENNY, CHRIS/-RP 

MODULE "SHEILA" REPLACED 
MODULE " LAURA1" REPLACED 
MODULE "LAURA2" REPLACED 
MODULE " JENNY 1" REPLACED 
MODULE "JENNY 2" REPLACED 

In this example, the /-RP switch is used to override the 
global format of the command. Object modules in files 
SHEILA, LAURA, and JENNY are processed as modules to be 
replaced, and file CHRIS is processed as a file that contains 
modules to be inserted. The resulting library file is shown 
in Figure 10-11. 

4. LBR>RICKLIB/RP=SHEILA, LAURA/-RP, JENNY 
MODULE "SHEILA" REPLACED 

LBR — * FATAL* — DUPLICATE MODULE "LAURAl" IN LAURA. OBJ; 1 

In this example, only module SHEILA from file SHEILA was 
replaced. The user specified that the modules in file LAURA 
not be replaced (/-RP), but inserted. One of the modules 
contained in file LAURA duplicated an already existing module 
in file RICKLIB (see Figure 10-8). Therefore, LBR issued the 
fatal error message and terminated the processing of the 
current command line. 





OUTPUT 
LIBRARY FILES 


INPUT FILES 


FILE NAME 


RICKLIB. OLB; 1 


SHEILA. OBJ; 1 


LAURA. OBJ ; 1 


JENNY. OBJ; 1 


CHRIS .OBJ; 1 




JENNY1 


SHEILA 


LAURAl 


JENNY1 


CHRIS1 


OBJECT 


JENNY2 




LAURA2 


JENNY2 


CHRIS2 


MODULES 


LAURAl 
LAURA2 
SHEILA 




LAURA 3 


JENNY3 
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Figure 10-8 Sample Files Used in LBR Examples 1-4 
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RICKLIB.OLB; 1 



JENNY1 

JENNY 2 

JENNY3" 

LAURA1 

LAURA 2 

LAURA3 3 

SH&ILA 



1. These modules did not exist in the 
library file prior to the execution of 
this example, but they did exist in the 
input files. LBR, therefore, assumed 
that they were to be inserted. Since 
LBR handled these modules as a normal 
insert, no message was printed on the 
input terminal. 
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Figure 10-9 Output Library File After Execution of Example 1 



RICKLIB.OLB;! 



CHRISl 
CHRIS2 ] 
JENNY 1 
JENNY 2 
LAURA 1 
LAURA 2 
SHEILA' 



1. These modules are inserted. 

2. This module is replaced. 
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Figure 10-10 Output Library File After Execution of Example 2 
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RICKLIB . OLB ; 1 
CHRISl 1 
CHRIS2 1 
JENNY 1 
JENNY 2 
JENNY 3 2 
LAURA 1 
LAURA 2 
LAURA3 2 
SHEILA 

1. These modules were specified to be 
inserted. Had a module of the same name 
been present, a fatal error message 
would have been issued. See Example 4. 

2. These modules were inserted by default . 

ZK-194-81 

Figure 10-11 Output Library File After Execution of Example 3 



10.5.13 Replace Switch (/RP) for Universal Libraries 

Use the /RP switch for universal libraries in the same way as for 
macro and object libraries. However, you can also specify the same 
values for the /RP switch as for the /IN switch for universal 
libraries (see Section 10.5.9). 

As with macro and object libraries, you can specify the /RP switch 
with either the output file specification or with the input file 
specifications. 

The global format of the /RP switch for universal libraries is: 
out file/RP: name :op:op:op:op=infile[,infile2,....infilen] 

The local format of the /RP switch for universal libraries is: 
outf ile=inf ile/RP:name :op:op:op:op[ ,infile2. ...infilen] 

outf ile 

Specifies the universal library file, 
infile 

Specifies the input file that contains replacement modules for 
the library file. The default for the file type is the value 
indicated at the universal library's creation time. (See Section 
10. 5. 2) . 
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Specifies the Replace switch. 

:name 

Optionally specifies the module name to be replaced (up to six 
Radix-50 characters) . The default is the first six characters of 
the infile name. 

:op 

Specifies optional descriptive information (up to six Radix-50 
characters) to be stored in the module header. The default is 
null. If only part of the information set is specified, all 
preceding colons must be supplied. 

Example 

LBR>TEXT . ULB=DEBB IE . TXT/RP: :THIS: IS: JAN3: UPDATE 
MODULE "DEBBIE" REPLACED 

In this example, LBR replaces the module DEBBIE in the universal 
library TEXT. ULB with an updated module from file DEBBIE. TXT. 
The date of replacement is specified by the optional user 
information and inserted in the module header. Note that the 
optional name is omitted. 

The initial state of the library file is shown in Figure 10-12. 
The resulting library file is shown in Figure 10-13. 





OUTPUT 
LIBRARY FILE 


INPUT FILES 


FILE NAME 


TEXT. ULB; 1 


DEBBI E .TXT 


MODULES 


DEBBIE 
BERNIE 
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Figure 10-12 Sample Files for Universal Library Replace Example 



TEXT. ULB; 1 



DEBBIE 
BERNIE 



l.The module DEBBIE was replaced. If a 
different infile were specified, that 
file would become module DEBBIE and 
occupy the same location in TEXT. ULB. 
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Figure 10-13 Output Library File After Execution of 
Universal Library Replace Example 
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10.5.14 Spool Switch (/SP) 

The Spool switch (/SP) is the list file default switch. Whether the 
switch is specified or not, the results are the same; that is, the 
listing file is spooled to the line printer. 

After the listing file is created, a request is made to the print 
spooler task to print the spooled file (see the RSX- 11M/M-PLUS Batch 
and Queue Operations Manual for a description of the spooler task) . 



The automatic printing of the listing file can be inhibited by 
specifying /-SP or /NOSP. This causes the listing file to be created, 
but the request to the print spooler task is not issued. Therefore, 
the file is not automatically printed. 

The /SP switch can only be appended to the list file specifier. 
The format for specifying the /SP switch is: 

outf ile,listf ile[/SP] or [/-SP] 
outf ile 

Specifies the library file, 
listf ile 

Specifies the listing file. 
/SP or /-SP 

Specifies the Spool switch. 
Example 

LBR>RICKLIB/DE : SHEILA, RICKLST/-SP 

In this example, the following occurs: 

1. The module SHEILA and its associated entry points are 
deleted from the library file SY:RICKLIB. 

2. The listing of the contents of the resulting library file 
RICKLIB is written to the list file SY: RICKLST. LST. 
Because the /-SP switch is specified, the file is not 
automatically printed. 



10.5.15 Selective Search Switch (/SS) 

Use the Selective Search switch (/SS) to set the selective search 
attribute bit in the module header of object modules as they are 
inserted into an object library. The switch has no effect when 
applied to modules being inserted into a macro library. The switch 
may be specified with input files for insertion or replacement 
operations only, and it affects all modules in the input file to which 
it is applied. 

Object modules with the selective search attribute are given special 
treatment by the Task Builder. Global symbols, defined in modules 
with the selective search attribute, are only included in the Task 
Builder's symbol table if they are previously referenced by other 
modules. Thus, only referenced symbols will be listed with the module 
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in the Task Builder memory allocation file, thereby reducing task 
build time. The /SS switch should only be applied to object files 
whose modules contain only absolute (not relocatable) symbol 
definitions. See the RSX-11M/M-PLUS Task Bui lder Manu al for more 
information. 

The format for specifying the /SS switch is: 

outf ile=infilel/SS[,infile2[/SS] , . . . inf ilen [/SS] ] 

outf ile 

Specifies the library file. 

infile 

Specifies the input file that contains modules to be selectively 
searched . 

/SS 

Specifies the Selective Search switch. 
Example 

LBR>ANGEL=JOHN, JILL/SS,MARK/SS,MARY 

The object files JOHN. OBJ, JILL. OBJ, MARK. OBJ, and MARY. OBJ are 
inserted into object library ANGEL. OLB. The selective search 
attribute bit is set in both the JILL and MARK object module 
header . 



10.5.16 Squeeze Switch (/SZ) 

Use the Squeeze switch (/SZ) to reduce the size of macro definitions 
by eliminating all trailing blanks and tabs, blank lines, and comments 
from macro text. The /SZ switch is used to conserve memory in the 
MACRO-11 Assembler and to reduce the size of macro library files. The 
/SZ switch has no effect on object libraries or universal libraries. 

The /SZ switch can be specified in either of two formats: 

• Global format - The /SZ switch is appended to the library file 
specification. All of the input files are assumed to contain 
modules to be squeezed. 

• Local format - The /SZ switch is appended to an input file 
specification. The /SZ switch works only on the file to which 
you append it. 

Global Format 

outfile/SZ=infilel[,infile2,...infilen] 
outf ile 

Specifies the library file. 
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/SZ 

Specifies the Squeeze switch, 
inf ile 

Specifies the input file that contains modules to be squeezed 
during insertion into the library file. 

Use the global format of the /SZ switch to specify a list of input 
files without having to append the /SZ switch to each of them. To 
override the global function for a particular input file (that is, to 
instruct LBR to process a particular file in a list as a file 
containing modules to be inserted but not squeezed) , append /-SZ or 
/NOSZ to the desired input file specification. 

Local Format 

outf ile=inf ilel/SZ [,inf ile2[/SZ] . . . , inf ilen [/SZ ] ] 
outf ile 

Specifies the library file, 
inf ile 

Specifies the file that contains modules to be squeezed during 
insertion into the library file. 

/SZ 

Specifies the Squeeze switch. 

LBR uses the following algorithm on each line to be squeezed and then 
inserts the resulting line into the library file: 

1. The line is examined for the rightmost semicolon (;). 

2. If a semicolon is located, it is deleted, along with all 
trailing characters in the line. 

3. All trailing blanks and tabs in the line are deleted. 

4. If the resulting line is null, nothing is transferred to the 
library file. 

If the line contains a semicolon embedded in noncomment text and you 
want comments squeezed, code a dummy comment for that line. The /SZ 
switch will use only the rightmost comment during squeeze processing. 

Example 

Figure 10-14 illustrates the use of the LBR /SZ switch. A file 
containing input text to be squeezed is illustrated, along with 
the text actually inserted into the library file after the 
squeeze operation has been completed. 
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BEFORE 




.MACRO 


MOVSTR RX , RY , ?LBL 


. ** * 

1 

7 


NOTE : 

BOTH ARGUMENTS MUST BE REGISTERS ; 


LBL: 


MOVB 

BNE 

DEC 


(RX)+,(RY)+ ;MOVE A CHARACTER 

LBL ; CONTINUE UNTIL NULL SEEN 

RY ; BACKUP OUTPUT PTR TO NULL 


;END 


OF MOVSTR 
.ENDM 


AFTER 


. *** 

LBL: 


.MACRO MOVSTR RX,RY,?LBL 
- - NOTE : 

BOTH ARGUMENTS MUST BE REGISTERS 

MOVB (RX)+,(RY)+ 

BNE LBL 

DEC RY 

.ENDM 
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Figure 10-14 MACRO Listing Before 
and After Running LBR with /SZ Switch 



10.6 COMBINING LIBRARY FUNCTIONS 

Two or more library functions may be requested in the same command 
line. The only exceptions are that /CO cannot be requested with 
anything else except /LI, and /CR and /DE cannot be specified in the 
same command line. 



Functions are performed in the following order: 



1. 


Default switch (/DF) 


2. 


Create switch (/CR) 


3. 


Delete switch (/DE) 


4. 


Delete Global switch (/DG) 


5. 


Modify Header switch (/MH) 


6. 


Insert (/IN), Replace (/RP) , Selective Search (/SS) , Squeeze 




(/SZ), Entry Point (/EP) switches 


7. 


Compress switch (/CO) 


8. 


Extract switch (/EX) 


9. 


List switches (/LI), /LE, /FU) , Spool switch (/SP) 


Example 





LBR>F ILE/DE : XYZ : $A, LP. LST : /LE/FU=MODX, MODY/RP 
Functions, performed in order, are: 
1. Delete modules XYZ and $A. 



2. Insert all modules from MODX and replace duplicate 
modules of MODY. 
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3. Produce a listing of the resultant library file on the 
line printer with full module descriptions and all entry 
points. 



10.7 LBR ERROR MESSAGES 

LBR returns two types of error messages: diagnostic and fatal. 

Diagnostic error messages describe a condition that requires 

consideration, but the nature of the condition does not warrant 

termination of the command. Diagnostic messages are issued to your 
terminal in the format: 

LBR — *DIAG* - message 

Fatal error messages describe a condition that caused LBR to terminate 
the processing of a command. When this occurs, LBR returns to the 
highest level of command input. For example, if the command is 
entered in response to the MCR prompt, that is, 

>LBR command 

then LBR issues the fatal error message and exits. If, however, the 
command is entered in response to the LBR prompt, that is, 

LBR>command 

LBR issues the fatal error message and reprompts. 

Fatal error messages are issued to your terminal in the format: 

LBR — * FATAL* - message 

If a fatal error occurs during the processing of an indirect command 
file, the command file is closed, the fatal error message - followed 
by the command line in error — is issued to your terminal and LBR 
returns to the highest level of command input. 



10.7.1 Effect of Fatal Errors on Library Files 

The status of a library file after fatal errors is: 

1. In general, output errors leave the library in an 
indeterminate state. 

2. During the deletion process, the library is rewritten prior 
to the printing of the individual module-/entry-point-deleted 
messages. 

3. During the replacement process, the library is rewritten 
prior to the printing of the individual module-replaced 
messages. 

4. During the insertion process, the library is rewritten after 
the insertion of all modules in each individual input file, 
that is, between input files. 
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10.7.2 LBR Error Messages 



LBR — BAD LIBRARY HEADER 

Explanation: The file is not a library file or it is corrupted. 
User Action: 

• If the file is not a library file, reenter the command line 
with a proper library file specified. 

• If the file is a proper library file, you should run the file 
structure verification utility (VFY) against the volume to 
determine if it is corrupted (see Chapter 9). 

• If the volume is corrupted, it must be reconstructed before 
it can be used. 



LBR -- CANNOT MODIFY HEADER 

Explanation: An attempt was made to modify the module header of 
a module in an object library or macro library. No change is 
made to the module header. 

User Action: Reenter the command line, specifying a module in a 
universal library. 



LBR — COMMAND I/O ERROR 

Explanation: One of the following conditions may exist: 

• A problem exists on the physical device (for example, not 
cycled up) . 

• The file is corrupted or the format is incorrect (for 
example, record length exceeds 132 bytes) . 

User Action: Determine which of the conditions caused the 
message and correct that condition. Reenter the command line. 



LBR — COMMAND SYNTAX ERROR 
command line 

Explanation: A command was entered in a format that does not 
conform to syntax rules. 

User Action: Reenter the command line, using the correct syntax. 



LBR — DUPLICATE ENTRY POINT NAME "name" IN filename 

Explanation: An attempt was made to insert a module into a 
library file when both contain an identically named entry point. 

User Action: Determine if the specified input file is the 
correct file. If not, reenter the command line, specifying the 
correct input file. If the input file is the correct file, you 
can delete the duplicate entry point from the library and reenter 
the command line. 
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LBR — DUPLICATE MODULE NAME "name" IN filename 

Explanation: An attempt was made to insert (without replacing) a 
module into a library that already contains a module with the 
specified name. 

User Action: Determine if the specified input file is the 
correct file. If the input file is correct, decide whether to 
delete the duplicate module from the library file and insert the 
new one, or replace the duplicate module with the /RP switch 
appended to the input file specification. 



LBR — EPT OR MNT EXCEEDED IN filename 

Explanation: The EPT or MNT table limit was reached during the 

execution of an insert or replace operation. 

User Action: Copy the library, increasing the table space by 

means of the Compress switch. Reenter the command line. 



LBR — EPT OR MNT SPACE EXCEEDED IN COMPRESS 

Explanation: An EPT or MNT table size was specified for the 
output library file that is not large enough to contain the EPT 
or MNT entries used in the input library file. 

User Action: Reenter the command line with a larger EPT or MNT 
table size specified. 



LBR — ERROR IN LIBRARY TABLES, FILE filename 

Explanation: The library file is corrupted or is not a library 
file. 

User Action: If the file is corrupted, no recovery is possible; 
the file must be reconstructed. If the file is not a library 
file, reenter the command line with the correct library file 
specified. 



LBR — EXACTLY ONE INPUT FILE MUST APPEAR WITH /CO 

Explanation: No input library file, or more than one file, was 
specified when using the /CO switch. 

User Action: Reenter the command line with only one input file 
specified . 



LBR — FATAL COMPRESS ERROR 

Explanation: The input library file is corrupted or is not a 
library file. 

User Action: No recovery is possible. The file in question must 
be reconstructed. 
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LBR — GET TIME FAILED 

Explanation: This error occurs when LBR attempts to execute a 
Get Time Parameters directive and fails. The error is caused by 
a system malfunction. 

User Action: Reenter the command line. If the problem persists, 
submit a Software Performance Report (SPR) along with the related 
console dialog and any other pertinent information. 



LBR — ILLEGAL DEVICE/VOLUME 
command line 

Explanation: The Device specifier entered does not conform to 
syntax rules. A device specifier consists of two ASCII 
characters, followed by one or two optional octal digits. 

User Action: Reenter the command line with the correct device 
syntax specified and followed by a colon. 



LBR — ILLEGAL DIRECTORY 
command line 

Explanation: The UFD entered does not conform to syntax rules. 
UFD syntax consists of a left square bracket, followed by one to 
three octal digits, a comma, one to three octal digits, and 
terminated by a right square bracket ([ggg,mmm]). 

User Action: Reenter the command line with the correct UFD 
syntax . 



LBR — ILLEGAL FILENAME 
command line 

Explanation: One of the following was entered: 

• A file specifier that contains a wildcard. 

• A file specifier that contains neither a file name nor a 
file type. 

User Action: Reenter the command line correctly. 



LBR — ILLEGAL GET COMMAND LINE ERROR CODE 

Explanation: The system, for some reason, is unable to read a 
command line. This is an internal system failure. 

User Action: Reenter the command line. If the problem persists, 
submit a Software Performance Report (SPR) along with the related 
console dialog and any other pertinent information. 



LBR — ILLEGAL SWITCH 
command line 

Explanation: A non-LBR switch was specified or a legal switch 
was specified in an invalid context. 

User Action: Reenter the command line with the correct switch 
specification . 
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LBR — ILLEGAL SWITCH COMBINATION 

Explanation: Switches were entered that cannot be executed in 

combination. See Section 10.6. 

User Action: Reenter the command line, specifying the switches 

in the proper combination. 



LBR — INDIRECT COMMAND SYNTAX ERROR 
command line 

Explanation: An indirect command file was specified in a format 
that does not conform to syntax rules. 

User Action: Reenter the command line with the correct syntax. 



LBR — INDIRECT FILE DEPTH EXCEEDED 
command line 

Explanation: An attempt was made to exceed one level of indirect 
command files. 

User Action: Rerun the job with only one level of indirect 
command file specified. 



LBR — INDIRECT FILE OPEN FAILURE 
command line 

Explanation: The requested indirect command file does not exist 
as specified. One of the following conditions may exist: 

• The user directory area is protected against access. 

• A problem exists on the physical device (for example, device 
cycled down) . 

• The volume is not mounted. 

• The specified file directory does not exist. 

• The file does not exist as specified. 

• Insufficient dynamic memory exists in the Executive. 

User Action: Determine which of the conditions caused the 
message and correct that condition. Reenter the command line. 



LBR — INPUT ERROR ON filename 

Explanation: The file system, while attempting to process an 
input file, has detected an error. A problem exists with the 
physical device (for example, the device cycled down) . 

User Action: Reenter the command line. 
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LBR — INSUFFICIENT DYNAMIC MEMORY TO CONTINUE 

Explanation: The partition in which LBR is running is too small 
for the task size. 

User Action: Remove the task (LBR), install it in a larger 
partition, and reenter the command line. (See the MCR INSTALL 
command description in the RSX-11M/M-PLUS MCR Ope rat ions Manual . ) 



LBR — INVALID EPT AND/OR MNT SPECIFICATION 

Explanation: An EPT or MNT value greater than 4096(10) was 

entered in a /CR or /CO switch. 

User Action: Reenter the command line with the correct value 
specified . 



LBR — INVALID FORMAT, INPUT FILE filename 

Explanation: The format of the specified input file is not the 
standard format for a macro source or object file, or the input 
file is corrupted. 

User Action: Reenter the command line with the correct input 
file specified. 



LBR — INVALID LIBRARY TYPE SPECIFIED 

Explanation: An invalid library type was specified when using 
the Create or Default switch. The values OBJ, MAC, and UNI are 
the only valid specifications. See Sections 10.5.2 and 10.5.4. 

User Action: Reenter the command line with OBJ, MAC, or UNI 
specified . 



LBR — INVALID MODULE FORMAT in insertion module 

Explanation: An attempt was made to insert a macro module into 
an object library. 

User Action: Determine if an object file was to be inserted into 

an object library. If so, reenter the command line with the 

correct object file. If a macro library was to receive the 

insertion, reenter the command line with the correct macro 
1 ibrary . 



LBR — INVALID NAME -- "name" 

Explantion: A module name that contains a non-Radix-50 character 
was specified for deletion, insertion, or replacement of a module 
in a universal library or in a macro module; or a module name 
was specified for modification of a universal module header. 
Radix-50 characters consist of the letters A through Z, the 
numbers through 9, and the special characters period (.) and 
dollar sign ($ ) . 

User Action: Reenter the command line with a valid name. 
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LBR — INVALID OPERATION FOR OBJECT AND MACRO LIBRARIES 

Explanation: Module header information was supplied for an 
object library or macro library in an insert or replace 
operation . 

User Action: No action required. The command will be executed 
as if the information had not been supplied. 



LBR — INVALID RAD50 CHARACTER IN "character string" 

Explanation: A character supplied as part of information when 
using the Insert, Replace, or Modify Header switches for a 
universal library is not a Radix-50 character. 

User Action: Determine which character of the corresponding 
switch value is not a Radix-50 character. Reenter a Radix-50 
character in place of the invalid character. 

LBR — I/O ERROR ON INPUT FILE filename 

Explanation: A read error has occurred on an input file. One of 
the following conditions may exist: 

• A problem exists on the physical device (for example, not 
cycled up) . 

• The file is corrupted or the format is wrong (record length 
exceeds 132 bytes) . 

User Action: Determine which of the conditions caused the 
message and correct that condition. Reenter the command line. 

LBR — LIBRARY FILE SPECIFICATION MISSING 

Explanation: A command line was entered without specifying the 
library file. 

User Action: Reenter the command line with the library file 
specified . 



LBR — MARK FOR DELETE FAILURE ON LBR WORK FILE 

Explanation: When LBR begins processing commands, it 
automatically creates a work file and marks it for delete. For 
some reason, this marking for delete failed. 

The work file constitutes a lost file because it does not appear 
in any file directory. 

User Action: The file may be deleted by running the file 
structure verification utility (VFY) (see Chapter 9). 



LBR — MULTIPLE MODULE EXTRACTIONS NOT PERMITTED FOR UNI MODULES 

Explanation: An attempt was made to extract more than one module 
from a universal library. The first module specified is 
extracted, but others are ignored. 

User Action: Reenter the command line for each additional 
extraction . 
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LBR — NO ENTRY POINT NAMED "name" 

Explanation: The entry point to be deleted is not in the 
specified library file. 

User Action: Determine if the entry point is misspelled or if 
the wrong library file is specified. Reenter the command line 
with the entry point or the library file correctly specified. 

LBR — NO MODULE NAMED "module" 

Explanation: The module to be deleted is not in the specified 
library file. 

User Action: Determine if the module name is misspelled or if 
the wrong library file is specified. Reenter the command line 
with the module name correctly specified. 



LBR — OPEN FAILURE ON FILE filename 

Explanation: The file system, while attempting to open a file, 
has detected an error. One of the following conditions may 
exist : 

• The user directory area is protected against an open. 

• A problem exists on the physical device (for example, device 
cycled down) . 

• The volume is not mounted. 

• The specified file directory does not exist. 

• The file does not exist as specified. 

• Insufficient contiguous space to allocate the library file 
(Compress and Create only) . 

• Insufficient dynamic memory exists in the Executive. 

User Action: Determine which of the above conditions caused the 
message and correct that condition. Reenter that command line. 



LBR — OPEN FAILURE ON LBR WORK FILE 

Explanation: The file system, while attempting to open the LBR 
work file, has detected an error. The LBR work file is created 
on the volume from which LBR was installed. One of the following 
conditions may exist: 

• The volume is full. 

• The device is wr ite-protected . 

• A problem exists with the physical device. 

• Insufficient dynamic memory exists in the Executive. 

User Action: Determine which of the conditions caused the 
message and correct that condition. Reenter the command line. 
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LBR — OUTPUT ERROR ON filename 

Explanation: A write error has occurred on the output file. One 
of the following conditions may exist: 

• The volume is full. 

• The device is wr ite-protected . 

• The hardware has failed. 

User Action: If the volume is full, delete all unnecessary files 
and rerun LBR. If the device is wr ite-protected , write-enable 
the device and reenter the command line. If the hardware has 
failed, swap devices and reenter the command line or wait until 
the device is repaired and rerun LBR. 



LBR — POSITIONING ERROR ON filename 

Explanation: A positioning error has occurred on the input file. 
One of the following conditions exist: 

• A problem exists on the physical device (for example it is not 
cycled up) . 

• The file is corrupted or the format is wrong. 

User Action: Determine which of the conditions caused the 
message and correct that condition. Reenter the command line. 



LBR — RMS MODULES CANNOT BE EXTRACTED TO RECORD ORIENTED DEVICES 

Explanation: An attempt was made to extract a module inserted 
from a nonsequential RMS file to a record-oriented device. This 
is a fatal error message. 

User Action: Extract the file to a disk and then use an RMS 
conversion to make an RMS sequential file. 



LBR — TOO MANY OUTPUT FILES SPECIFIED 

Explanation: More than two output files were specified. LBR 
makes the following assumptions: 

• The first output file specified is the output library file. 

• The second output file specified is the listing file. 

• The third through n files specified to the left of the equal 
sign are ignored. 

User Action: No action is required. LBR continues as though the 
extra file(s) had not been specified. 
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LBR — VIRTUAL STORAGE REQUIREMENT EXCEEDS 65536 WORDS 

Explanation: This error may occur if you are working with 
maximum size libraries and you specify a single command line that 
first logically deletes a large number of modules and entry 
points, then replaces them with an equally large number of 
modules and entry points that have names much different from 
those being replaced. Normally, this message indicates some sort 
of internal system error. 

User Action: Rerun the job, but divide the complicated command 
line into several smaller command lines that do the same 
operations . 



LBR — WORK FILE I/O ERROR 

Explanation: A write error has occurred on the LBR work file. 
One of the following conditions may exist: 

• The volume is full. 

• The device is wr i te-protected . 

• The hardware has failed. 

User Action: If the volume is full, delete all unnecessary files 
and rerun LBR. If the device is wri te-protected , write-enable 
the device and reenter the command line. If the hardware has 
failed, swap devices and retry the command, or wait until the 
device is repaired and rerun LBR. 



10-42 



CHAPTER 11 
FILE DUMP UTILITY (DMP) 



The File Dump Utility (DMP) enables the user to examine the contents 
of a specific file or volume of files. The output may be formatted in 
ASCII, octal, decimal, hexadecimal, or Radix-50 form and dumped to any 
suitable output device such as a line printer, terminal, magnetic 
tape, DECtape, or disk. 

You can dump the header and/or virtual blocks of a file or only the 
virtual records of a file. If you are dumping a volume, a range of 
logical blocks may be specified (see Sections 11.1 and 11.2). DMP 
normally handles blocks of up to 256(10) words in length. If the 
maximum block size exceeds 256(10) words, DMP's buffer size must be 
increased as follows: 

>RUN $DMP /INC=n 

The value of the variable n must be equal to a multiple of 8 that is 
equal to or greater than the maximum length block or record minus 
256(10) words. 

The same restriction applies when dumping records greater than 512(10) 
bytes. In this case, you must increase DMP's buffer size by altering 
the DMPBLD.CMD or DMPANSBLD.CMD file as required, then rebuilding the 
task. See the appropriate system generation manual and your system 
manager for more specific information on altering various features of 
DMP. 

You can invoke DMP by using any of the methods described in Chapter 1. 
After DMP is invoked, it prompts: 

DMP> 

DMP is now ready for user input in the form of a command line. 

DMP operates in two basic modes: file mode and device mode. File 
mode is used to dump virtual records or virtual blocks, and device 
mode is used to dump logical blocks. 



11.1 FILE MODE 

In file mode, one input file is specified, and all or a specified 
range of virtual blocks are dumped. You can also dump all the virtual 
records of a specified file in this mode. The input device must be 
either a Files-11 formatted disk or a magnetic tape. The volume must 
be mounted using the MCR MOUNT Command. 
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NOTE 

If the input medium is magnetic tape, 
DMP must be built with ANSLIB instead of 
SYSLIB. 



In file mode, you can specify that data be dumped one record or one 
block at a time. A virtual block or record refers to one block or 
record of data in a file. Virtual blocks and records are numbered 
sequentially from 1 through n, where n is the total number of blocks 
or records in the file. Virtual block contains the header of the 
file. Use the /BL:n:m switch to dump virtual blocks and the /RC 
switch to dump virtual records. The /BL and /RC switches are mutually 
exclusive. (DMP switches are listed in Table 11-1.) 



11.2 DEVICE MODE 

In device mode, only the input device is specified, and a specified 
range of logical blocks is dumped. The /BL:n:m switch is a required 
parameter in this mode. 

A logical block refers to a physical 512-byte block on disk or DECtape 
and to physical records on magnetic tape or cassette. Logical blocks 
are numbered from to n-1, where n is the total number of logical 
blocks on the device. 

On RSX-11M, when DMP is in device mode, do not mount the volume. 
On RSX-11M-PLUS, however, the volume roust be mounted foreign. 



11.3 DMP COMMAND FORMAT 

The command line for DMP is in the following format: 

[outfile] [/sw] [/sw. . . ] =inspec [/sw] [/sw. . . ] 
outf ile 

Specifies the output file. If the output file name and file type 
are unspecified, DMP creates the file DMPFIL.DMP. If the file 
type is .DMP, the file will be deleted after it is printed. TI: 
and LP: (for terminal and line printer) are also acceptable 
outfile specifications. 

On RSX-11M, if you specify LP:, the file will not print if the 
print despooler is active. 

On RSX-11M-PLUS, transparent spooling is implemented. When you 
specify LP: as your output device, the data to be printed is 
written into an intermediate file and then the file is given to 
the Queue Manager, which handles the spooling. 

/sw 

Specifies one of the switches listed in Table 11-1. Unless 
otherwise indicated in a switch description, all switches can be 
applied either to the input file or to the output file with equal 
effect. DMP will allow multiple dumps in a single command line. 
Therefore, any or all of the current format switches may be 
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specified. Certain switches are mutually exclusive. For 
example, the /HX, /LW, and /WD switches, are mutually exclusive 
hexadecimal dump switches. The first one in the following order 
will be the only one executed: /LW, /WD, /HX. 

inspec 

Specifies the input device and file or input device only. In 
file mode, the equal sign and the input file name and file type 
are required because DMP does not provide a default for either of 
them. However, the input file version number defaults to the 
latest version and the device defaults to SY: and the current 
UIC. 

In device mode, the equal sign and input device are required as 
is the /BL:n:m switch which specifies the range of logical blocks 
to be dumped. 

For a complete description of file specifications, see Chapter 1. 



11.4 DMP SWITCHES 

DMP switch specifications consist of a slash (/) followed by a switch 
name, optionally followed by a value. The value is separated from the 
switch by a colon (:). DMP functions are implemented by the switches 
described in Table 11-1. 



Table 11-1 
DMP Switches 



Switch 



Description 



Default 



/AS 



/BA:n :m 



The default is a word mode octal dump, 
is spooled to the line printer. 



which 



Specifies that the data should be dumped one 
byte at a time in ASCII mode. The control 
characters (0-37) are printed as a circumflex 
("), followed by the alphabetic character 
corresponding to the character code plus 100. 
For example, bell (code 7) is printed as ~G 
(code 107) . Lowercase characters (140-177) 
are printed as a percent sign (%), followed 
by the corresponding uppercase character 
(character code minus 40), unless the /LC 
switch is specified. Note that the /AS and 
/OCT switches are mutually exclusive when 
dumping bytes. 

Specifies a 2-word base block address (the 
initial base address is 0,0), where n is the 
high-order base block address (octal) , and m 
is the low-order base block address (octal). 
The address may also be specified in decimal 
by using a period after the number. All 
future block numbers specified by the /BL 
switch will be added to this value to obtain 



(continued on next page) 
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Table 11-1 (Cont.) 
DMP Switches 



Switch 



/BA:n:m (Cont.) 



/BL:n :m 



Description 



an effective block number. This switch is 
useful for specifying block numbers that 
exceed 16 bits. For example: 

DMP>/BA: 1: 

specifies that all future block numbers will 
be relative to 65536(10) (200000(8)). 

DMP>/BA: 0: 

clears the base address. Once the /BA switch 
is specified, it remains in effect until it 
is used again to set a new base address. 

When the /BA switch appears in a command 
line, no blocks are dumped. The only result 
of the command line is to set the base 
address . 

Specifies the range of blocks to be dumped, 
where n is the first block and m is the last 
block. The values of n and m must not exceed 
16 bits. In file mode only, the /BL switch 
is not required. If the /BL switch is not 
specified, DMP will dump all blocks of the 
specified file, relative to the current base 
address . 



If /BL:n:m is specified in file mode, it 
specifies the range of virtual blocks to be 
dumped. If /BL:n:m is specified as /BL: in 
file mode, no virtual blocks are dumped. 
This is useful for dumping only the header 
portion of the file (see /HD) . The /BL 
switch and the /RC switch are mutually 
exclus ive . 



The /BL:n:m switch is a required parameter in 
device mode. When used in device mode, it 
specifies the range of logical blocks to be 
dumped . 

Magnetic tapes and cassettes, when dumped in 
device mode, are always dumped starting with 
the current tape position, that is, the 
values given with the /BL switch are ignored. 
The switch values are used, however, to label 
the pages of the dump listing and to 
determine the number of blocks to dump. 

When a switch value of /BL:n:m is specified, 
(m-n)+l blocks are dumped, starting at the 
current tape position. The value n 
represents the block number of the first 



(continued on next page) 
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Table 11-1 (Cont.) 
DMP Switches 



Switch 



Description 



/BL:n:m (Cont.) 

/BY 
/DC 

/DENS :n 



/FI: file-number 
sequence-number 



/HD[:F or :U] 



block dumped. Successive blocks are labeled 
with a block number one higher than the 
preceding block number. The dump will 
continue until the block labeled m is dumped. 



Specifies that the data be dumped 
byte format. 



in octal 



Specifies that the data be dumped in decimal 
word format. 

Specifies the density of an input magnetic 
tape with 800, 1600, and 6250 bpi capability, 
when DMP is in device mode only. The value 
for n can be 800, 1600, or 6250. 

DMP does not automatically determine the 
density of an input tape. If the /DENS 
switch is not specified in a DMP command 
line, DMP attempts to read an input tape at 
the density currently set in the tape 
controller. (See the RSX-11M/M-PLUS MCR 
Operations Manual and th~i RSX-11M/M-PLUS 
Command Language Manual for descriptions of 
the MOUNT command and its /DENS switch.) 

In File Mode, the file number can be used 
instead of a file name as a file 
specification for input. 

This switch is an optional parameter used in 
File Mode. If specified, the /HD switch 
causes the file header as well as the 
specified or implied portion of the file to 
be dumped. 

Example : 

DMP>TI : =JMF. DAT/HD/BL: 5: 6 

This example dumps the header of JMF.DAT in 
header format and virtual blocks 5 and 6 in 
octal format. 

In addition, this switch has two options. 
"F", the default, causes a Files-11 formatted 
dump of the header. "U" specifies an 
unformatted octal dump. An octal dump also 
occurs when DMP is used on non-Files-11 
headers . 

If you want only the header portion of the 
file to be dumped, specify: 

/HD/BL: 



(continued on next page) 
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Table 11-1 (Cont.) 
urif bwitcnes 


Switch 


Description 


/HD [ : F or : U] 
(Cont. ) 


File headers are described in the IAS/RSX— 11 
I/O Operations Reference Manual. 


/HF 


Specifies the format for data blocks that 
have the Files-11 header structure. Other 
blocks are output as an unformatted octal 
dump. 

Example,: 

DMP>HEAD. LST= [0,0] INDEXF . SYS/HF 
This example generates a dump of the index 

file INDEXF. SYS and format*; all the* headers 

X. 1 1 ^ X x.^ JL/ J_i /\ JL • U J.U UllU X.UJL11IGUO all LUC IlCuU CIO 

in the file. 


/HX 


Specifies that the data be dumped in 
hexadecimal byte format. Note that a 
hexadecimal dumD reads from riaht to left. 
(See also the /LW and /WD switches.) 


/ID 


Causes DMP's version to be identified. This 
switch may be specified on a command line by 
itself at any time. 

Example : 

DMP>/ID 

DMP — DMP VERSION M07.1B 
For DMP built with ANSLIB, the response is 
DMP — DMP VERSION M07.1B (ANSI) 


/LB 


Requests logical block information for a 
file. The starting block number and a 
contiguous or noncontiguous indication for 
the file are displayed. 

Example : 

DMP>TI: =DK0: RICKSFILE.DAT ;3/LB 
STARTING BLOCK NUMBER = 0,135163 C 

The file RICKSFILE.DAT, version 3, is a 
contiguous file starting at block number 
0,135163. (See /BA:n:m for block number 
description . ) 


/LC 


Specifies that the data should be dumped in 
lowercase characters. This switch can only 
he used if the outDiit dpvicp ha^ lowercase 

capabil ity. 




(continued on next page) 
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Table 11-1 (Cont.) 
DMP Switches 



Switch 



Description 



/LW 

/MD[:n] 



/OCT 



Specifies that the data be dumped in 
hexadecimal double-word format. 

Specifies a memory dump and allows control of 
line numbers. Line numbers are normally 
reset to zero whenever a block boundary is 
crossed. The /MD switch allows lines to be 
numbered sequentially for the full extent of 
the file, that is, the line numbers are not 
reset when block boundaries are crossed. The 
optional value (:n) specifies the value of 
the first line number. The default is 0. 
The /MD switch is used with the output file 
specification . 

Specifies that the data should be dumped in 
octal format in addition to other formats 
specified. If no DMP format switches are 
specified, the default is octal. The /AS 
switch and the /OCT switch are mutually 
exclusive when dumping bytes. 



/R5 
/RC 



/RW 



Specifies that data 
Radix-50-format words. 



be dumped 



in 



Specifies that data be dumped a record at a 
time (rather than a block at a time) . The 
data format is determined by setting any of 
these format switches: /AS, /DC, /HX, /LW, 
/R5, or /WD. 

The largest record that DMP can process is 
limited by, the amount of space available to 
the DMP tasc. DMP's task image has 512(10) 
bytes allocated to it initially. To increase 
the amount of space available, use the MCR 
INSTALL command /INC switch. For example, to 
dump a file with 1024-byte records, you must 
specify /INC=256. (at least) . If the input 
is a tape and the block size is greater than 
512 bytes, $FSR1 must be expanded as 
described in the DMPBLD.CMD or DMPANSBLD.CMD 
file. 

The /RC switch and the /BL switch are 
mutually exclusive. 

Causes DMP to issue a rewind command before 
referencing a specified tape. This switch 
may be specified at any time to reposition a 
tape at the beginning-of-tape (BOT) . 



(continued on next page) 
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Table 11-1 (Cont.) 
DMP Switches 


Switch 


Description 


/SB:n 
or 

/CD . 

/ dd . — n 


Specifies the number of blocks DMP spaces 
forward (n) or backward (-n) on tape. DMP 
SLopa wnen it acnsea ena ot tape ^nui j . uhjt 
will space only single blocks beyond EOT. 


/SF:n 

or 
/SF: -n 


Specifies the number of end-of-file (EOF) 
marks DMP spaces forward (n) or backward (-n) 
on tape. DMP stops when it senses EOT or 
BOT. DMP will space only single EOF marks 
De yonu EiU i • 


/SP 


Causes the dump output file to be spooled to 
the line printer. The /SP switch may only be 
specified on the output file specification; 
it is illegal on the input file 
specification. Spooled files may be deleted 
after printing. 


/WD 


Specifies that the data be dumped in 
hexadecimal word format. 



11.5 DMP EXAMPLES 

Three examples of dump listings are included in this section to 
illustrate how the various DMP switches can be used. DMP edits blocks 
or records 16(10) bytes at a time. The dump includes the indicated 
number of valid bytes in the block or record. The remaining number of 
bytes are listed as null bytes (0). 



11.5.1 A Multiple Format Dump 

The command line shown in Example 11-1 dumps virtual blocks 5 and 6 of 
DSC. MAC in hexadecimal, Radix-50, and decimal format. Each line of 
the output file will appear in three different formats. 
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Example 11-1 Dumping Virtual Blocks in Hexadecimal, 
Radix-50, and Decimal Format 



DMP>DOC . DMP=C301 » 357 D DSC . MAC/HX/R5/DC/BL : 5 : 6 
The contents of DOC. DMP are: 



DUMP OF DBOJ C301,3573DSC.MACJ1 - FILE ID 17725,11*0 
VIRTUAL BLOCK 0,000005 - SIZE 512. BYTES 

4E 41 4D 4D 4F 43 20 41 20 3B 00 IE 53 45 52 49 0000 J Hexadecimal 
000000 MFY ML7 EFK EFQ L$K LN/ LT3 JRadix-50 
0. 21065. 21317. 00030, 08251. 08257, 20291. 19789. 20033 . i Decimal 

53 45 53 53 45 43 4F 52 50 20 44 4E 41 20 2C 44 0010 
000020 6CL JF'2 J7F L22 L*Z KCK MMK ML7 

16. 11332. 16672. 17486. 20512. 20306. 17731. 21331. 21317. 
53 52 49 46 20 3B 00 39 00 3B 00 01 2E 54 49 20 0020 



DUMP OF DBOt C301 , 357 D DSC . MAC » 1 - FILE ID 17725,11,0 
VIRTUAL BLOCK 0,000006 - SIZE 512. BYTES 



20 44 4E 46 55 42 24 20 51 45 20 30 52 20 46 49 0000 
000000 KI3 MEX EF M E E1H MYZ LT8 EFT 

0. 17993. 21024. 08240. 20805. 09248. 21826. 20038. 08260. 

44 4E 45 09 00 09 50 4F 4F 4C 20 45 56 41 45 4C 0010 
000020 KCT M2A EFU L*T L39 I KA3 J7F 

16. 17740. 22081. 08261. 20300. 20559. 00009. 17673. 17486. 
54 53 24 20 54 45 4C 09 00 2B 00 50 4F 4F 4C 20 0020 
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11.5.2 A Record Dump 

The command line shown in Example 11-2 dumps all of the virtual 
records of YACHT. SEQ in ASCII and decimal word format. 



Example 11-2 Dumping Virtual Records in ASCII and Decimal Word Format 



DMP>REC. DMP=C 301 ,3573 YACHT .SEQ/RC/ AS/DC 



The contents of REC.DMP are: 



DUMP OF DB0:C7»3373YACHT.SEQJ 1 - FILE ID 15451, 35r0 
RECORD NUMBER 01. - SIZE 41. BYTES 



000000 ALBER 6 37 MK 

0. 19521. 17730. 18258. 08224. 08224. 14131. 19744. 08267. 

000020 II KETCH 37 200 

16. 18761. 08224. 17739. 17236. 08264. 14131. 12832. 12336. 

000040 1 2 3 6 9 5 1 ~@ ~@ ~@ ~(? ~@ ~@ ~@ 

32. 12336. 12849. 13875. 13625. 00049. 00000. 00000. 00000. 



RECORD NUMBER 02. - SIZE 41. BYTES 



000000 A L B I N 7 9 

0. 19521. 18754. 08270. 08224. 08224. 14647. 08224. 08224. 

000020 SLOOP 26 042 

16. 08224. 08224. 19539. 20303. 08272. 13874. 12320. 12852. 

000040 1 1 7 9 "0 "0 "0 "0 ~0 "0 "0 

32. 12336. 12337. 14129. 12345. 00048. 00000. 00000. 00000. 



11.5.3 A Header Dump 

The command line shown in Example 11-3 dumps only the header of 
DSC. MAC. 



11-10 



FILE DUMP UTILITY (DMP) 



Example 11-3 Dumping the File Header of a File 



DMP>DHR.DMP=C301»357DDSC,MAC/HD/BL:0 



The contents of DHR.DMP are: 



DUMP OF DB0:C301,3573DSC.MACil - FILE ID 17725,11,0 

FILE HEADER 



HEADER AREA 
H ♦ IDOF 
H.MPOF 
H.FNUM, 
H.FSEG 
H.FLEV 
H.FOWN 
H.FPRO 
H. UCHA 
H.SCHA 
H.UFAT 



027 
056 

(17725,11) 
401 

C301 ,3573 

CRUEDf RUEDf RUEDf R3 

000 = 
000 = 



F.RTYP 002 = R ♦ VAR 

F.RATT 002 = FD ♦ CR 

F.RSIZ 116 = 78. 

F ♦ H IBK HJO LJ000040 = 32* 

F ♦ EFBK HJO LJ000040 = 32. 

F.FFBY 532 = 346. 

(REST) 

000000 000000 000000 000000 000000 000000 000000 000000 
000000 
IDENTIFICATION AREA 



1 . FNAM » 






I ♦ FTYP » 






I . FVER 




DSC .MACJ1 


I ♦ RVNO 




1 


I.RVDT 




13-0CT-80 


I » RVTI 




09J52M6 


1 ♦ CRDT 




13-0CT-80 


I.CRTI 




09J52M5 


I.EXDT 






MAP AREA 






M.ESGN 




000 


M.ERVN 




000 


M . EFNU » 






M.EFSQ 




(0,0) 


M.CTSZ 




001 


M.LBSZ 




003 


M.USE 




014 = 12. 


M.MAX 




314 - 204. 


M.RTRV 






SIZE 


LBN 




12. 


h:ooo 


LJ036215 ■ 15501. 


3. 


h:ooo 


LJ036235 = 15517. 


1 . 


HJ000 


L:036250 = 15528. 


2. 


HJ000 


LJ036272 « 15546. 


3. 


h:ooo 


LJ036313 = 15563. 


11 ♦ 


HtOOO 


LJ036411 » 15625. 


CHECKSUM 






H.CKSM 




122620 



11-11 



FILE DUMP UTILITY (DMP) 

11.6 DMP ERROR MESSAGES 

DMP — BAD DEVICE NAME 

Explanation: An incorrect device name was entered in a file 
specification. 

User Action: Reenter the command line specifying the correct 
device . 

DMP — BLOCK SWITCH REQUIRED IN LOGICAL BLOCK MODE 

Explanation: Self-explanatory (/BL must be specified.) 

User Action: Reenter the command line specifying the /BL switch. 

DMP — CANNOT FIND INPUT FILE 

Explanation: The requested file cannot be located in the 
specified directory. 

User Action: Reenter the command line specifying the correct 
file name and UFD. 

DMP ~ COMMAND SYNTAX ERROR 

Explanation: A command line was entered in a format that does 
not conform to syntax rules. 

User Action: Reenter the command line specifying the correct 
syntax . 

DMP — FAILED TO ASSIGN LUN 

Explanation: An illegal device was entered in a file 
spec i f ication . 

User Action: Reenter the command line specifying the correct 
device . 

DMP — FAILED TO READ ATTRIBUTES 

Explanation: A file was specified for which you did not have 
read access privileges. 

User Action: Rerun DMP under a UIC that has read access 
privileges to the file. 

DMP — ILLEGAL DENSITY VALUE 

Explanation: A value other than 800, 1600, or 6250 bpi was 
specified with the DMP /DENS switch. 

User Action: Reenter the /DENS switch with the proper value. 

DMP — ILLEGAL SWITCH 

Explanation: A switch was specified that is not a valid DMP 
switch, or a legal switch was used in an invalid manner. 

User Action: Reenter the command line specifying the correct 
switch. 
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DMP — ILLEGAL USE OF /RC SWITCH 

Explanation: The /RC switch can be used only in file mode (see 
Section 11.1). 

User Action: Reenter the command line specifying a file name. 

DMP — ILLEGAL VALUE ON HD SWITCH 

Explanation: An option was entered other than F or U for the /HD 
switch. 

User Action: Reenter the command line specifying the correct 
option . 

DMP — I/O ERROR ON INPUT FILE 
or 

DMP — I/O ERROR ON OUTPUT FILE 

Explanation: One of the following conditions exists: 

• A problem exists on the physical device (for example, the 
device cycled down) . 

• The file is corrupted or the format is incorrect. 

• The output volume is full. 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 

DMP — NO INPUT FILE SPECIFIED 

Explanation: A command line was entered with no input file 
specification. 

User Action: Reenter the command line specifying an input file. 

DMP — NO LISTS OR WILD CARDS ALLOWED 

Explanation: Either a command line with more than one input or 
output file name was entered, or a wildcard was entered as a file 
specification . 

User Action: Reenter the command line, specifying only one input 
file specification and one output file specification. No 
wildcard specifications are allowed. 

DMP — OPEN FAILURE ON INDIRECT FILE 

Explanation: The requested indirect command file does not exist 
as specified. One of the following conditions exists: 

• The file is protected against access. 

• A problem exists on the physical device (for example, the 
device cycled down) . 

• The volume is not mounted. 



11-13 



FILE DUMP UTILITY (DMP) 



• The specified file directory does not exist. 

• The named file does not exist in the specified directory. 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 

DMP — OPEN FAILURE ON INPUT FILE 

or 

DMP — OPEN FAILURE ON OUTPUT FILE 

Explanation: One of the following conditions exists: 

• The file is protected against access. 

• A problem exists on the physical device (for example, the 
device cycled down) . 

• The named file does not exist in the specified directory. 

• The volume is not mounted. 

• The specified file directory does not exist. 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 
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CHAPTER 12 



THE FILE COMPARE UTILITY (CMP) 



The File Compare Utility (CMP) compares two ASCII text files. The 
files are compared line by line to determine whether parallel records 
are identical. Using CMP, you can perform the following file-compare 
functions : 

• Generate a listing showing the differences between the two 
files. Each difference is listed as a pair: first, the lines 
from the first file, then the lines from the second file. 

• Generate a listing in the form of one list, with differences 
marked by change bars. 

• Generate output suitable for input to the Source Language 
Input Program utility (SLP) . This output contains the SLP 
commands and input required to make the first input file 
identical to the second input file. (For more information on 
SLP, see Chapter 13.) 

CMP provides switches that allow you to control compare processing. 
Using these switches, you can control comparison of blanks, tabs, form 
feeds, and comments. You can also control line numbering and specify 
the number of lines required for CMP to consider that a match has been 
made between lines in the two files. 

The format for specifying the CMP command line is: 

[outf ile [/sw. ..]=] infilel,infile2 



The file specification for the output file. This file can be in 
one of three formats, depending on the switch you specify in the 
command line. The defaults are: 



However, if you do not specify an output file, the output 
defaults to your terminal. For example: 

CMP>F I LEI. MAC, FILE 2. MAC 



outf ile 



SYO: 

[current UIC] 

FILCOM 

. LST 



The user's default system device 
The UIC that CMP is running under 
The default file name 
The default file type 
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CMP lists the differences between FILE 1 . MAC and FILE 2. MAC on your 
terminal. If you type the equal sign but give no output file 
specification, only the total number of differences is output to 
your terminal. For example: 

CMP>=FILE1.MAC;1,FILE2.MAC;1 
10 differences found 

/sw. . . 

Switches that you apply to the output file specification. Some 
of the switches can be negated and some are mutually exclusive. 
Section 12.1 contains this information. 

inf ilel 

The file specification for the input file to be compared to 
infile2. The file name of this file must be specified. The 
default file type is .MAC. 

inf ile2 

The file specification for the input file to be compared to 
infilel. You do not have to have a complete file specification. 
The specifications for infilel are used as defaults for any 
unspecified portions of infile2. For example: 

CMP> DB 2 : [42,10] EXEC , ; 2 

CMP interprets the second input file as DB2: [42, 10] EXEC. MAC; 2. 

If you do not specify a file version number, the default is the most 
recent version of the file. 

You can invoke CMP using any of the methods for invoking a utility 
described in Chapter 1. 



12.1 CMP SWITCHES 

This section lists the CMP switches, describes the function of each 
one, and gives the default setting for each one. You specify switches 
after the output file in the command line. 

/BL Specifies that blank lines in both files be included in 

/-BL compare processing. If this switch is specified in the form 

/-BL, blank lines are not included in compare processing. 

/-BL is the default switch. 

/CB Specifies that CMP list infile2 with change bars, in the 

/-CB form of exclamation marks (!), to denote which lines do not 

have a corresponding line in infilel. When a section of 
lines in infilel has been deleted in infile2 (the output 
listing file), the first line not deleted is marked. /-CB 
is the default switch. 

You can change the change bar character from the exclamation 
mark to any character you wish by means of the /VB switch, 
described later. 

/CO Specifies that CMP include comments (that is, text preceded 

/-CO by a semicolon) in compare processing. /CO is the default 

swi tch . 
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/DI Specifies that CMP list the differences between the two 

/-DI files (rather than marking the lines in inf ile2) . /DI is 

the default switch. 

/CB and /DI are mutually exclusive switches. If you specify 
both, /CB overrides /DI. 

/FF Specifies that CMP include records consisting of a single 

/-FF form-feed character in compare processing. /-FF is the 

default switch. 

/LI:n Specifies that a number (n) of lines must be identical 

before CMP recognizes a match. /LI: 3 is the default switch. 

When it encounters a match, CMP lists all the preceding 
nonmatching lines, along with the first line of the matched 
sequence of lines to help you find the location in the code 
where the match occurred. 

/LN Specifies that lines in the output file be preceded by 

/-LN their line number. Line numbers are incremented by one for 

each record read, including blank lines. /LN is the default 
switch. If you specify /SL, /LN is unnecessary. 

/MB Specifies that CMP include all blank and tab characters in a 

/-MB line in compare processing. If you specify /-MB, CMP 

interprets any sequence of blank and/or tab characters as a 
single blank character. However, all spaces and tabs are 
printed in the output listing. /MB is the default switch. 

/SL[:au] Directs CMP to generate an output file suitable for use as 
SLP command input. When you specify /SL, CMP generates the 
SLP command input necessary to make infilel identical to 
infile2. If a 1- to 8-character alphanumeric symbol is 
included after the /SL switch (:au), an audit trail is 
specified for SLP input. Section 12.2.3, gives an example 
of how CMP generates SLP command input. (For information on 
how SLP processes source files, refer to Chapter 13.) /-SL 
is the default switch. 

/SP[:n] Specifies that the output file be spooled on the line 
/-SP printer. You can optionally specify the number (in octal or 

decimal) of files to be spooled. /-SP is the default 
switch. This switch applies only if you have the Print 
Spooler task (RSX-11M) or the Queue Manager system 
(RSX-11M/M-PLUS) installed. 

/TB Specifies that CMP include all trailing blanks on a line 

/-TB in compare processing. If you specify /-TB, CMP ignores all 

blanks following the last nonblank character on a line. 

When you specify /-CO and /-TB together, blanks that precede 

a semicolon (;) are considered trailing blanks and are 

ignored. /TB is the default switch. 

/VB:nnn Specifies an octal character code for the character you want 
to use as a change bar. You use this switch with the /CB 
switch. The value nnn specifies the octal character code. 
For example, you can specify /VB:174 for a vertical bar (if 
your printer is capable of printing the vertical bar 
character). /VB:041 for an exclamation mark is the default 
switch. 

CMP default switch settings are listed in Table 12-1. 
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Table 12*1 
Summary of CMP Default Switch Settings 



/-r r 


Do not compare blanks. 




/—PR 


Do not generate change bars. 




/CO 


Compare comments. 




/DT 


List only the differences between the two 


files . 


/-FF 


Do not compare form-feed characters. 




/LI: 3 


Find three identical lines before a match 


can occur. 


/LN 


Generate numbered lines. 




/MB 


Compare all blank and tab characters. 




/-SL 


Do not generate an output file suitable for use as 




SLP command input. 




/-SP 


Do not spool the output file. 




/TB 


Compare all trailing blanks. 




/VB: 041 


Set the exclamation mark (ASCII 041) as 
bar character. Used with /CB. 


the change 



12.2 FORMATS OF CMP OUTPUT FILES 

CMP uses the two input files you specify on the command line to 
create an output file. CMP compares each line in infilel to its 
sequential counterpart in infile2. When there are differences 
between the two files, CMP displays those differences in one of 
three output formats: 

• Differences format (default) (/DI) 

• Change bar format (/CB) 

• SLP command input format (/SL) 

This section gives an example of each of these formats. In the 
examples in the subsequent sections, the following files are used as 
infilel (TEST1.DAT;!) and infile2 (TEST2.DAT;!): 



DBO: [7,7]TEST1.DAT;1 DBO: [7, 7] TEST2. DAT; 1 



LINE 1 

LINE2 

LINE3 

LINE4 

LINE5 

12345 

23456 

34567 

LINE9 

LINE10 

LINE11 

EXTRA 



LINE 1 

LINE2 

LINE3 

LINE4 

LINE5 

45678 

56789 

67891 

LINE9 

LINE10 

LINE11 

EXTRA 

EXTRA 

EXTRA 

EXTRA 
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12.2.1 Differences Format 

If you enter a command line and do not specify any switches, CMP lists 
the differences between the two files on your terminal or in an output 
file. The differences are listed in pairs; first, the lines from 
infilel that do not have counterparts in infile2 are listed, then the 
lines from infile2 that do not have counterparts in infilel are 
listed. Each set of lines is terminated by the first line (or set of 
lines) for which a match is successful. 

The following example shows the format of output generated without any 
switches. The output file is generated with the CMP command: 

CMP>TESTDIF . DAT=TEST1 . DAT, TEST2 . DAT 

********************************************* 

1) DBO: [7 , 7] TEST1 . DAT ; 1 

6 12345 

7 23456 

8 34567 

9 LINE9 
***************** 

2) DBO: [7, 7] TEST2.DAT ; 1 

6 45678 

7 56789 

8 67891 

9 LINE9 

********************************************* 

1) DBO: [7, 7] TEST1.DAT ; 1 
***************** 

2) DBO: [7, 7]TEST2. DAT; 1 

13 EXTRA 

14 EXTRA 

15 EXTRA 

2 differences found 

The input files are TEST1.DAT and TEST2.DAT, which are shown in 
Section 12.2. There are two sets of differences separated by a long 
line of asterisks. (When there are several sets of differences, CMP 
separates each set from the next set by a long line of asterisks.) The 
short line of asterisks separates the pair of differences that 
comprise the set. 

Note that because /LI:n was not specified, the number of lines 
required for a match defaults to 3. Thus, CMP found two differences. 



12.2.2 Change Bar Format 

You use the /CB switch to generate a listing containing change bars 
that show the differences between two files. In the CMP command line, 
infile2 is the listing you want generated. 

The following example shows the format of output with change bars 
applied to lines from two files that do not match line for line. The 
output file is generated with the CMP command: 

CMP>TESTDIF . DAT/CB=TEST1 . DAT, TEST2 . DAT 

Notice that the change bar is applied to the first line of match (line 
9) . 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 



LINE1 

LINE2 

LINE3 

LINE4 

LINE5 

45678 

56789 

67891 

LINE9 

LINE10 

LINE11 

EXTRA 

EXTRA 

EXTRA 

EXTRA 



2 differences found 



12.2.3 SLP Command Input Format 

You use the /SL[:au] switch to generate a file containing records to 
be used as SLP command input. /SL directs CMP to generate the SLP 
edit command lines and input lines required to make infilel identical 
to infile2. 

However, you must enter the command line with SLP command input. CMP 
does not generate this command line. For a complete description of 
the SLP utility, refer to Chapter 13 in this manual. 

The following example shows the format of output generated using the 
/SL switch. The output file is generated with the CMP command: 

CMP>TESTDIF . DAT/SL: BLS 001=TEST1 . DAT, TEST2. DAT 

-6, 8,/;BLS001/ 

45678 

56789 

67891 

-12, ,/;BLS001/ 

EXTRA 

EXTRA 

EXTRA 

/ 



12.3 CMP MESSAGES 

This section lists the CMP messages, gives a brief description of the 
condition that causes each message, and suggests a response to the 
condition. 



CMP — n differences found 

Explanation: CMP found n differences between the two files. 
User Action: This is an informational message. 
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CMP — Command syntax error 

Explanation: CMP found an error in the command line syntax. 

User Action: Check the syntax of the command line specification 
and reenter the command line using the correct syntax. 



CMP — Error reading input file 

Explanation: An I/O error occurred while CMP was reading an 
input file. 

User Action: Reenter the command line. 



CMP — Error writing output file 

Explanation: An I/O error occurred while CMP was 
output file. 

User Action: The output device may be full or bad. 

then reenter the command line. 



CMP -- Illegal /LI value 

Explanation: You specified a negative value for 
lines required for a match. 

User Action: Reenter the command line with 
specified . 



CMP — Illegal switch or switch value 

Explanation: An illegal switch or switch value was entered in 
the command line. 

User Action: Reenter the command line using a legal switch or 
switch value. 



CMP — Open failure on input file #1 

Explanation: CMP could not open the first input file. 

User Action: Check the file specification for first input file 
and reenter the command line using the correct file 
specification. 



CMP — Open failure on input file #2 

Explanation: CMP could not open the second input file. 

User Action: Check the file specification for second input file 
and reenter the command line using the correct file 
specification . 



writing the 
Check this, 



the number of 
a legal value 
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CMP — Open failure on output file 

Explanation: CMP could not open the specified output file. 

User Action: Check the file specification for the output file 
and reenter the command line using the correct file 
specification. 



CMP — Too many differences for available core 

Explanation: The files were too dissimilar for CMP to fit all 
the differences in memory. 

User Action: Rerun CMP using the /INC=n switch, or remove and 
reinstall CMP with a larger increment. (For information on using 
/INC=n, see the description of the INSTALL command in the 
RSX-11M/M-PLUS MCR Operations Manual . ) 
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SOURCE LANGUAGE INPUT PROGRAM (SLP) 



The Source Language Input Program (SLP) is a utility used to maintain 
and audit source files. The optional audit trail in the output files 
allows you to keep a record of maintenance changes. 

SLP is invoked by edit command statements and switches. SLP edit 
command statements allow you to: 

• Update (delete, replace, add) lines in an existing file 

• Create source files 

• Run indirect files containing SLP edit commands 

Input to SLP is a file that you want updated and command input 
consisting of text lines and edit command lines that specify the 
update operations to be performed. To locate lines to be changed, SLP 
uses line numbers or character strings that you specify. Command 
input can come directly from your terminal or from an indirect command 
file containing commands and text lines to be inserted into the file. 
SLP accepts data from any Files-11 volume. 

Output from SLP is a listing file and the updated input file. SLP 
provides an optional audit trail that helps you keep track of the 
update status of each line in the file. If an audit trail is not 
suppressed, it is shown in the listing file and permanently applied to 
the output file. 

You can control SLP processing with SLP control switches. These 
switches allow you to: 



• 


Suppress audit trails 






• 


Specify the length and beginning 


position 


of the audit trails 


• 


Calculate the checksum value for 


the edit 


commands 


• 


Generate a double-spaced listing 






• 


Spool files to a Files-11 volume 







You can invoke SLP by all but one of the methods for invoking a 
utility described in Chapter 1. You cannot include a command line on 
the same line on which you invoke SLP. That is, you cannot type: 

>SLP filespec 

Also, you should not specify TI: as your output file, because when 
you finish editing, you will not have a copy of the output file and 
the input file will be the same as before you began editing. 
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13.1 SLP INPUT AND OUTPUT FILES 

SLP requires two types of input, an input file and command input. The 
input file is the source file you want to update using SLP. Command 
input consists of SLP edit commands and, optionally, new lines of text 
to be placed in the file. 

SLP output consists of an output file and a listing file. The output 
file is the updated input file. The listing file is a copy of the 
output file with line numbers added. Both show the changes SLP made 
to the file. 



13. 1. 1 The Input File 

The input file is the file to be updated by SLP. It can contain as 
many lines of text as are required. When SLP processes the input 
file, it makes the changes specified by SLP edit commands. If an 
audit trail is generated, these changes are noted in the output files. 



13.1.2 Command Input 

SLP uses command input to update files. Command input can be entered 
interactively after you invoke the SLP utility or indirectly by means 
of indirect command files. 

You enter command input to SLP in two modes: command mode and edit 
mode. After it is invoked, SLP is in command mode, where the first 
line entered must be the command line defining the files to be 
processed. When SLP accepts this line, it initializes the files you 
want processed. Once these files are initialized, SLP enters edit 
mode, where it interprets the lines you enter as SLP edit commands or 
new input lines. 

You terminate command input with a single slash as the first character 
of an edit command line. 

The following example shows the general form of command input: 

MYFILE.MAC;2/CS/AU: 55: 10 , MYF ILE . LST ; 1/-S P=MYF ILE . MAC ; 1 

-3, ,/;BJ007/ 

CMP (R1)+,B 

-4,4 

DEC R2 

/ 



NOTE 

Numeric values given for switches 
default to octal. Decimal values must 
be followed by a period (.). The 
default position for the audit trail is 
80(10) and its default length is 8(10); 
no more than 14(10) characters may be 
specified. (See Section 13.4.2 for more 
information about the audit trail.) 
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The first line is the command line, where you define the output file, 
the listing file, and the input file. The next four lines comprise 
the SLP edit commands and input lines. 

Note that the input and output files in the example have the same file 
name and file type; only the versions are different. To ensure that 
the correct files are processed, specify the version numbers 
explicitly when you enter the SLP command line. Wildcards cannot be 
used in any of the file specifications. 

You can also calculate the checksum value for the edit commands. 
Specify the checksum switch with either the input or output file 
specification in the format: 

/CS [:n] 

The checksum value can be calculated for all SLP edit command lines. 
The checksum value cannot be calculated for the following: 

• The command line specifying the input and output files 

• Comments in the edit command lines 

• Any spaces and/or tabs between characters included in the 
checksum calculation and those characters excluded from the 
calculation 

• The second comma and anything following it in an edit command 
line (that is, audit trail and/or comment) 

• Comment delimiter (specified by the first character of the 
last audit trail string before the current delimiter) and any 
characters following it in an input line, whether or not it is 
being used in the line as a delimiter 

The value is then reported in a message on your terminal. If you 
specify a value for the checksum and it is not the same as the 
calculated checksum, you will get a diagnostic error message. (The 
messages are described in Section 13.5.2) 



13.1.3 The SLP Listing File 

The SLP listing file shows the updates made to the source file. Each 
line in the listing file is numbered. Updates are marked by means of 
the audit trail if one has been generated. The examples given 
throughout this chapter contain samples of listing files. 



13.1.4 The SLP Output File 

The SLP output file is the updated input file. All of the updates 
specified by command input are inserted in this file. The audit 
trail, if specified, is applied to lines changed by the update. The 
audit trail is included in the output file. The numbers generated by 
SLP for the listing file do not appear in the output file. 
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13.2 HOW SLP PROCESSES FILES 

Figure 13-1 shows how SLP processes files when it receives the 
following command line and edit commands: 

MYFILE . MAC ;2/AU: 55: 10 , MYFILE . LST/-S P=MYF ILE . MAC ; 1 
-3 

CMP (R1)+,B 
-4,4 

DEC (R2) 
/ 



Input File 



Listing File 



MYFILE.MAC;1 



MYFILE. LST;1 



Command Input 



From Primary From Indirect File 

Input Device or INFILE.SLP;1 




SLP 
Processor 



Output File 



MYFILE.MAC;2 



Figure 13-1 Input Files and Output Files Used During SLP Processing 



This is the input file (MYFILE. MAC ; 1 ) before SLP processes the files: 



MOV 


#BUF1,R0 


MOV 


#SIZ,R1 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLR 


Rl 


MOV 


R2,NUMC 


CMPB 


(R0)+,A 


BNE 


20$ 


INC 


Rl 
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The following is the listing file (MYFILE. LST; 1 ) 
processing of these files: 



resulting from SLP 



1. 


MOV 


#BUF1, R0 


2. 


MOV 


#SIZ , Rl 


3. 


CALL 


READ 


4. 


CMP 


(R1)+,B 


5. 


DEC 


(R2) 


6. 


BEQ 


END 


7. 


CLR 


Rl 


8. 


MOV 


R2,NUMC 


9. 


CMPB 


(R0)+,A 


10. 


BNE 


20$ 


11. 


INC 


Rl 



;**NEW** 
; **NEW** 
;**-! 



The audit trail shows the new lines (;**NEW**) and indicates where 
lines have been removed (;**-l). (The audit trails ;**NEW** and ; **-n 
are automatically generated by SLP if you have not suppressed audit 
trail generation or if you have not specified another audit trail 
string.) In this case, a line has been added after line 3, and line 4 
has been deleted and a new line added in its place. 

As shown in Figure 13-1, SLP processes an input file using command 
input. When processing begins, SLP writes each line from the input 
file into the output file until it reaches a line to be modified, as 
requested in the command input. When SLP reaches a line to be 
modified, it modifies the line, notes the change by means of the audit 
trail, and then continues writing lines to the output file until 
another command is encountered or until end-of-file is reached. 



13.3 USING SLP 

This section describes how to: 

• Specify the SLP edit commands 

• Update files using the SLP edit commands 

• Enter SLP commands interactively and by means of indirect 
command files 

• Create a source file using SLP 



13.3.1 Specifying SLP Edit Commands 

The SLP edit commands allow you to update source files by adding, 
deleting, and replacing lines in a file. SLP allows you to enter 
lines sequentially. Once past a given line in the file, you cannot 
return the line pointer to that line. To return the line pointer to 
that line, you must begin another SLP editing session. You enter SLP 
edit commands after invoking SLP and specifying an edit command line. 

The general format of the SLP edit command line is as follows: 

-[locatorl] [,locator2] [ ,/audittrail/] [; comment] 
inputl ine 
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- (dash) 

Identifies a SLP edit command line, 
locator 1 

A line locator that causes SLP to move the current line pointer 
to a specified line. If you specify only locatorl, the current 
line pointer is moved to that line and SLP reads the next line in 
the command input file. This field can be specified using any of 
the locator forms described later in this section. 

locator2 

A line locator that defines a range of lines (that is, the range 
beginning with locatorl and ending with locator2, inclusive) to 
be deleted or replaced. This field can be specified using any of 
the locator forms described later in this section. 

/audittrail/ 

A character string used to keep track of the update status of 
each line in the file. The string must be enclosed within 
slashes (/) . It consists of a comment delimiter as the first 
character and then a text string. The semicolon (;) is the 
default delimiter for audit trails automatically generated by SLP 
(;**NEW** and ; **-n) . The comment delimiter specified in 
audittrail (usually a semicolon) Is the new delimiter for all 
subsequent audit trails until redefined by a later audittrail. 

inputline 

A line of new text to be inserted into the file immediately 
following the current line. You can enter as many input lines as 
requi red . 

comment 

A line of text (delimited by a semicolon) at the end of the SLP 
edit command line that appears only in the command input file. 

All fields in the SLP edit command line are positional and commas must 
be specified. 

The locator fields can take one of the following forms: 

-/st r ing/ [+n] 
-/string . . . str ing/ [+n] 
-number [+n] 
[+n] 

string 

A string of ASCII characters. SLP locates the line where the 
string exists and moves the current line pointer to that line. 
If the locator is specified in the form /str ing ... str ing/ , SLP 
locates the line where the two character strings delimit a larger 
character string abbreviated by an ellipsis (...). 

number 

A decimal line number where the current line pointer is to be 
moved. The largest line number that can be specified is 9999. 
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. (period) 

The current line. 



n 

A decimal value used as an offset from the line specified by the 
locator. You cannot use +n by itself. It must be specified with 
a number or string locator or a period. SLP moves the current 
line pointer n lines beyond the line specified in the locator 
field. 

Although the values for number and n are taken as decimal, remember 
that all other SLP values are octal by default. 

All forms of the line locator can be specified interchangeably in the 
SLP edit command lines. 



13.3.2 Entering SLP Edit Commands 



Once you have invoked SLP, you can enter SLP edit commands 
interactively or by specifying indirect command files. In both cases, 
the first command you must enter is the command line defining the 
files to be processed during this SLP session. This section gives 
examples of how to use both methods of entering SLP commands. 

The following file (BASE.MAC;1) is used as the input file for the 
examples in this section: 



MOV #$SWTCH,R3 

CLR $ERFLG 

CLR $CRCVL 

CLR $CSSV 

MOV SPSAV,SP 

MOV #$CFNMB,R0 

MOV #<$HDSIZ-$CFNMB>/2+l,Rl 

CLR (R0) + 

DEC Rl 

BNE 5$ 



13.3.2.1 Entering SLP Commands Interactively - To alter the example 
file interactively, first invoke SLP by using any method described in 
Chapter 1 (except >SLP f ilespec) . 

SLP responds to this command with the prompt: 

SLP> 

Once you have entered the SLP command mode, SLP does not display 
prompts. The first line you enter must always be the command line 
defining the files you want processed during this session: 

BASE. MAC ; 2/AU: 48 . /TR , BASE . LST=BASE . MAC ; 1 
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Then you enter the edit commands and input lines: 
-3 

TST Rl 
-4,4 

BEQ 10$ 
-6, ,/; JM010/ 
CLR R2 
/ 

In this example, the edit commands instruct SLP to do the following: 
-3 inserts a new line after line 3; -4,4 deletes line 4 and replaces 
it with a new line; -6,,/;JM010/ inserts a line after line 6 with a 
new audit trail value. 

When you have entered all the corrections, enter the slash (/) to 
terminate the edit session. SLP processes the files and returns 
control to you with the prompt: 

SLP> 

This returns SLP to command mode. You can then enter another input 
file and begin another editing session. 

The listing file ( BASE. LST ; 1 ) resulting from SLP processing appears as 
follows : 



1. 


MOV 


#$SWTCH,R3 




2. 


CLR 


$ERFLG 




3. 


CLR 


$CRCVL 




4. 


TST 


Rl 


; **NEW** 


5. 


BEQ 


10$ 


; **NEW** 


6. 


MOV 


SPSAV, SP 


.**_! 


7. 


MOV 


#$CFNMB,R0 




8? 


CLR 


R2 


; JM010 


9. 


MOV 


#<$HDSIZ-$CFNMB>/2+l,Rl 




10. 


CLR 


(R0) + 




11. 


DEC 


Rl 




12. 


BNE 


5$ 





The /TR switch (/TR in the command line) records the truncation of 
lines by the audit trail. In the listing file, a question mark (?) 
replaces the period (.) after the line number for the lines that were 
truncated. It is possible that audit-trail strings in the input file 
will be truncated by the new audit-trail string, although the commands 
or text strings will not be truncated. 



13.3.2.2 Entering SLP Commands Using Indirect Command Files - To 

alter the example file by using the SLP edit commands in the indirect 
command file, BASE. SLP, you invoke SLP and SLP responds with the 
prompt : 

SLP> 

You then enter the file specification for the indirect command file 
containing the command line, the SLP edit commands, and the input 
1 ines : 

@BASE . SLP 
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SLP processes the files just as if you entered the commands and input 
lines interactively, returning control to you with the prompt: 

SLP> 

You can also specify SLP @BASE.SLP. 

The output listing resulting from indirect command file processing is 
exactly like the output listing resulting from the same changes made 
interactively. 

Indirect command files can be nested to a maximum level of three. 
This permits indirect command files to reference a text file. 



13.3.2.3 Using SLP Operators - In addition, you can enter special 
characters called operators, which perform specific functions. Table 
13-1 lists the operators and the function each performs. Enter 
operators, in edit mode, as the first character of an input line. 



Table 13-1 
SLP Operators 



Operator 



Function 



Identifies the first character of a SLP edit command 
1 ine . 



Suppresses audit-trail processing. 
Reenables audit-trail processing. 

Invokes an indirect command file for SLP processing. 

Terminates the SLP edit session, and then returns to 
SLP command mode. 

Enables you to enter characters in the input file 
that SLP otherwise would interpret as operators. For 
example, </ hides the slash character from SLP, 
thereby enabling you to enter the slash into the 
output file without terminating the SLP editing 
session. This character can be used with all SLP 
operators . 



13.3.3 Updating Source Files With SLP 

This section describes the procedure for generating a numbered listing 
for use in editing source files by line number. The section also 
describes how to use SLP to add, delete, and replace lines in a file. 



13.3.3.1 Generating a Numbered Listing - SLP processes input by line 
number. However, line numbers appear only in the listing file; they 
are not written to the output file. 
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To use SLP effectively, you should use a numbered listing when you 
prepare command input. To generate a numbered listing, first invoke 
SLP, then enter the command line in the format: 

, 1 istf ile=inf ile 
/ 

In this format, listfile is the name you assign to the listing file 
SLP will produce and infile is the name of the input file whose lines 
are to be numbered. The slash (/) terminates edit mode. For example, 
suppose the input file is: 



MOV 


R1,-(SP) 


BIC 


#177770, @SP 


ADD 


#60,<aSP 


MOVB 


(SP) + ,-(R0) 


ASR 


Rl 


ASR 


Rl 


ASR 


Rl 


DEC 


R2 


BNE 


30$ 


MOV 


#MSG,R0 



SLP processes each line to generate a numbered list file (list 



f ile;l) : 






1. 


MOV 


R1,-(SP) 


2. 


BIC 


#177770, @SP 


3. 


ADD 


#60,(3SP 


4. 


MOVB 


(SP) + ,-(R0) 


5. 


ASR 


Rl 


6. 


ASR 


Rl 


7. 


ASR 


Rl 


8. 


DEC 


R2 


9. 


BNE 


30$ 


10. 


MOV 


#MSG,R0 



13.3.3.2 Adding Lines to a File - The three SLP edit command formats 
for adding lines to a file are: 

-locatorl 
inputl ine 



or 

-locatorl , , 
inputl ine 

or 

locatorl, ,/aud ittrail/ 
inputl ine 
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The following example shows how to add lines to a file. The command 
input consists of the following lines: 

MYFILE . MAC ; 2/AU: 48. : 10 . /TR, MYF ILE . LST/-S P=MYFILE . MAC ; 1 
-3 

CMP (R1)+,B 
-4, 4 

DEC R2 
-6, , ,/; JM010/ 
INC R3 
-9, f /;BJ008/ 
BEQ 10$ 
/ 

The next example uses text rather than line numbers to indicate where 
new lines should be added or deleted: 



MYFILE. MAC; 2/AU: 50, MYFILE. LST=MYF ILE . MAC ; 1 
-/BEQ/ 

CALL WRITE 
/ 



In this example, the edit command /BEQ/ instructs SLP to insert a line 
after the line with the first occurrence of BEQ. 

SLP processing generates the following listing file (MYFILE. LST ; 1 ) : 



1. 


MOV 


#BUF1,R0 


2. 


MOV 


#SIZ,R1 


3. 


CALL 


READ 


4. 


TST 


R2 


5. 


BEQ 


END 


6. 


CALL 


WRITE 


7. 


CLR 


Rl 


8. 


MOV 


R2,NUMC 


9. 


CMPB 


(R0) + , A 


10. 


BNE 


20$ 


11. 


INC 


Rl 



;**NEW** 



SLP has numbered the lines and applied an audit trail to the line 
following line 5, where SLP found the first occurrence of the string 
BEQ. 

The next example uses the same input file and the following new 
command lines: 



MYFILE. MAC ;2/AU: 50 , MYF ILE . LST=MYF ILE . MAC ;1 

-/#SIZ/+2 

CMP (R1)+,B 

/ 



SLP processing generates the following listing file (MYFILE;!) 



1. 


MOV 


#BUF1, R0 


2. 


MOV 


#SIZ ,R1 


3. 


CALL 


READ 


4. 


TST 


R2 


5. 


CMP 


(R1)+,B 


6. 


BEQ 


END 


7. 


CLR 


Rl 


8. 


MOV 


R2,NUMC 


9. 


CMPB 


(R0)+,A 


10. 


BNE 


20$ 


11. 


INC 


Rl 



;**NEW** 
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Again, SLP has numbered the lines and this time the new input line is 
inserted so that it is two lines beyond the line containing the first 
occurrence of the string /#SIZ/. 



13.3.3.3 Deleting Lines from a File - The SLP edit command format for 
deleting lines from a file is: 

-[locatorl] , [locator2] , [/audittrail/] [; comment] 

In this format, locatorl and locator2 can be any of the forms of the 
locator fields described in Section 13.3.1; locatorl specifies the 
line where SLP is to begin deleting lines; locator2 specifies the 
last line to be deleted. SLP deletes all lines from locatorl through 
locator2, inclusive. 

The following example shows how to delete lines from a file. The 
input file consists of the following lines: 



MOV 


#BUF1,R0 


MOV 


#SIZ, Rl 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLR 


Rl 


MOV 


R2,NUMC 


CMPB 


(R0)+,A 


BNE 


20$ 


INC 


Rl 



The command input consists of the following commands and text lines: 

MYFILE . MAC ; 2/AU: 50 , MYFILE. LST=MYFILE.MAC ; 1 

-/MOV. . . Rl/,/NUMC/ 

/ 

SLP processing generates the following listing file (MYFILE ; 1 ) : 

1. MOV #BUF1,R0 

2. CMPB (R0)+,A 

3. BNE 20$ 

4. INC Rl ;**-6 

In this example, the ellipsis (...) abbreviates the larger string MOV 
#SIZ,R1. Assuming the two strings bracket a larger string, SLP 
searches for the first occurrence of the string MOV and then the first 
occurrence on the same line of the string Rl, in this case the string 
MOV #SIZ,R1. SLP begins deleting lines at this line and continues 
deleting lines until it deletes the last line of the given range, 
specified here by the string NUMC. SLP applies the audit-trail count 
of the lines it deleted to the next line from the input file. 

Using the same input file as used in the previous example, the 
following example shows how to delete a single line using the period 
locator. The command input for this example is: 

MYFILE. MAC; 2/AU: 50 , MYF ILE . LST=M YF ILE . MAC ; 1 

-/MOV #SIZ,R1/,. 

/ 
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SLP processing generates the following listing file (MYFILE ; 1 ) : 



1. 


MOV 


#BUF1, RO 


2. 


CALL 


READ 


3. 


TST 


R2 


4. 


BEQ 


END 


5. 


CLR 


Rl 


6. 


MOV 


R2,NUMC 


7. 


CMPB 


(R0)+,A 


8. 


BNE 


20$ 


9. 


INC 


Rl 



SLP moves the current line pointer to the line containing the string 
MOV #SIZ,R1 and then finds the period as the second locator field. 
Since the second locator field is specified as the current line, SLP 
deletes the current line. 



13.3.3.4 Replacing Lines in a File - A replacement is the deletion of 
old text followed by the insertion of new text. The number of lines 
deleted need not match the number of lines added. To replace lines in 
a file, use the same SLP edit command format as used in the delete 
command. The first line locator field specifies the first line to be 
deleted. The second line locator field defines the last line in the 
range to be deleted and where the new text is to be inserted. For 
example : 



-4 , . +4 

This command instructs SLP to move the line pointer to line 
replace line 4 and the next four lines with new input lines. 



4, and 



The following example shows how to delete lines from a file and 
replace them with new lines. The input file consists of the following 
1 ines : 



MOV 


#BUF1,R0 


MOV 


#SIZ , Rl 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLR 


Rl 


MOV 


R2,NUMC 



The command input is: 

MYFILE. MAC ; 2/AU: 50 , MYFILE. LST=MYF ILE . MAC ; 1 



-2, 


.+1 




CMP 


(R1)+,B 




INC 


R2 




/ 






In this 


example, the edit command, -2, 


.+1, instructs SLP to 


lines 2 


and 3 and insert two new lines 




SLP processing generates the following 


listing file (LISTING;1) 


1. 


MOV #BUF1,R0 




2. 


CMP (R1)+,B 


;**NEW** 


3. 


INC R2 


; **NEW** 


4. 


TST R2 


; **-2 


5. 


BEQ END 




6. 


CLR Rl 




7. 


MOV R2,NUMC 





delete 
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13.3.4 Creating Source Files Using SLP 

Using SLP to create source files is possible, but not recommended. 
SLP does not have an intraline editing mode and you cannot return to a 
line once you have passed it. An interactive editor, such as EDI or 
EDT, is better for creating source files. 

To create source files using SLP, invoke SLP and enter the command 
line in the format: 

outf ile/-AU[/sw] [ ,listf ile] [/sw] = [primary input device : [/sw] ] 

outf ile 

The file specification for the output file. The default device 
is SYO:. 

/-AU 

Specifies that an audit trail is not to be generated. Otherwise, 
you will get the ;**NEW** audit trail on every line of the output 
files. 

listf ile 

The file specification for the listing file (optional). The 
default device is implied by the output file specification. 

primary input device: 

Specifies that input for the file being created is coming from 
this device, for example, a terminal. The default device is your 
primary input device. 

/sw 

Specifies any optional SLP switches. 

The following file specification creates a new file called MYFILE.MAC 
from the terminal and puts it on SYO:. 

MYFILE . MAC/-AU=TI : 

Once you have entered the file specification, SLP accepts each line as 
a variable-length record of up to 132(10) characters. Trailing blanks 
and tabs on input lines are deleted. SLP expects input to the file to 
come from the primary input device. End the SLP session with a slash 
(/) and then a CTRL/Z. 



13.4 CONTROLLING SLP 

The SLP switches allow you to calculate the checksum value for the 
edit commands and to control the generation and format of the listing 
file and the output file. 



13. 4. 1 SLP Switches 

SLP output consists of two files — a listing file and the output 
file, which is the modified version of the input file. You can use 
the SLP switches to control the audit trail and print options 
associated with the two files. 
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The effects of SLP switches are the same whether you apply them to 
input or output files (except for the /SP switch, which you can 
specify only with the listing file). Table 13-2 lists the SLP 
switches and gives a brief description of the functions each performs. 



Table 13-2 
SLP Switches 


Switch 


Function 


/AU 
/-AU 


Allows you to generate an audit trail or suppress 
audit-trail generation and specify the beginning 
field and length of the audit trail. /AU is the 
default value. See the following sections for more 
information about the /AU switch. 


/BF 
/-BF 


Positions the audit trail by inserting spaces instead 
of tabs at the end of text information. /BF is the 
default value. 


/CM[:n] 


Deletes audit trails and any trailing spaces or tabs, 
and truncates the text at a specified horizontal 
position. The value given for the beginning position 
of the audit trail is the default value for this 
switch. See Section 13.4.6 for more information 
about the /CM switch. 


/CS[:n] 


Calculates the checksum value for the edit commands. 
If you do not specify n, SLP reports the value in a 
message on your terminal. If you do specify n and 
the checksum value that SLP calculates is not the 
same as the one you specified, SLP displays a 
diagnostic error message. The procedure SLP uses to 
calculate the checksum value for the edit commands is 
described in Section 13.1.2. 


/DB 
/-DB 


Generates the listing file in double-space format. 
/-DB is the default value. 


/SP 
/-SP 


Spools the listing file to the printer. /SP is the 
default value. This switch applies only if you have 
the print spooler task (RSX-11M) or the queue 
management system (RSX-1 1M/M-PLUS ) on your system. 


/TR 


Reports truncation of lines by the audit trail. If 
line truncation occurs, you will get a diagnostic 
error message. There is no default value for this 
switch. 

In the listing file, a question mark (?) replaces the 
period (.) in the line number of the lines that were 
truncated . 




(continued on next page) 
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Table 13-2 (Cont.) 
SLP Switches 


Switch 


Function 


/SQ 


Sequences the lines in the output file so that the 
numbers reflect the line numbers of the original 
input file. New lines added to the file have the 
same number as the preceding line. This allows the 
MACRO Relocatable Assembler to output listing files 
that contain the original line numbers, thus easing 
the process of updating correction files. 

If you specify a listing file, SLP preserves the line 
numbers of the inDiit file hut" flnp? not - H 1 einl 
numbers for the new lines that have been inserted. 


/RS 


Resequences the lines in the output file so that the 
line numbers are incremented for each line written to 
the output file. The /RS switch overrides the /SQ 
switch. 


/NS 


Does not sequence the lines in the output file. New 
lines are indicated by the audit trail (if 
specified). The /NS switch is the default condition 
and overrides the /SQ and /RS switches. 



13.4.2 Controlling the Audit Trail 

The /AU switch allows you to generate, suppress, and set the length 
and contents of the audit trail. To suppress generation of the audit 
trail, specify the /-AU switch in either the input or output file 
specification. 

For example, either of the following command lines generates an output 
file with no audit trail: 

DKlrMYFILE.MAC ; 3/-AU, LP. LST: =MYFILE.MAC ; 2 

DK1 : MYF ILE . MAC ; 3 , LP. LST : =MYF ILE . MAC ; 2/-AU 

LP. LST will be spooled automatically. 

By default, SLP automatically generates an audit trail; that is, you 
need not explicitly specify the /AU switch in your command line 
(unless you want to specify the beginning position and length of the 
aud it trail ) . 
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13.4.3 Setting the Position and Length of the Audit Trail 

You can set the beginning position of the audit trail and the length 
of the audit trail using the /AU switch in the format: 

/ AU :position:l eng th 

position 

A number, less than or equal to 132(10), designating the 
beginning character position of the audit trail on the line. SLP 
rounds this value to the next highest tab stop (a multiple of 8) . 
The default value for position is 80(10). 



NOTE 

Numeric values given for switches default to octal. 
Decimal values must be followed by a period (.). The 
default position for the audit trail is 80(10) and its 
default length is 8(10); no more than 14(10) characters 
may be specified. (See Section 13.4.2 for more 
information about the audit trail.) 



length 

The length of the audit trail. The default value for length is 
8(10) characters; no more than 14(10) characters may be 
specified . 



The following example shows how to specify the beginning position and 
length of the audit trail. The input file for this example is: 



MOV #BUF1,R0 

MOV #SIZ,R1 

CALL READ 

TST R2 

BEQ END 



The command input is: 

MYFILE . MAC ; 2/AU: 30. : 10./TR,MYFILE. LST/-SP=MYFILE.MAC ; 1 

-2, .+1,/; CHANGE 001/ 

CMP (R1)+,B 

DEC R2 

/ 

The listing file MYFILE. LST;1 resulting from SLP processing is: 



1. MOV #BUF1,R0 

2. CMP (R1)+,B 

3. DEC R2 

4. TST R2 

5. BEQ END 



CHANGE001 
CHANGE001 
**-2 



13.4.4 Changing the Value of the Audit Trail 

To change the value of the audit trail, specify: 
-[locatorl] , [locator2] ,/;new value/ 
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The following example shows how to change the audit trail values. The 
input file consists of the following lines: 



MOV 


#BUF1, RO 


MOV 


#SIZ ,R1 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLR 


Rl 


MOV 


R2,NUMC 


CMPB 


(R0)+,A 


BNE 


20$ 


INC 


Rl 



The command input consists of the following commands and text lines: 

MYFILE . MAC ; 2/AU: 48. : 10 . /TR, MYFILE . LST/-S P=MYF ILE . MAC ; 1 
-3 

CMP (R1)+,B 
-4,4 

DEC R2 
-6, ,/; JM010/ 
INC R3 
-9, ,/;BJ008/ 
BEQ 10$ 
/ 

In this example, the edit commands instruct SLP to insert a line after 
line 3, to delete and replace line 4, and to insert new lines after 
lines 6 and 9 with new audit trail values. 

The listing file (MYFILE. LST) resulting from SLP processing appears as 
follows : 



1. 


MOV 


#BUF1,R0 




2. 


MOV 


#SIZ , Rl 




3. 


CALL 


READ 




4. 


CMP 


(R1)+,B 


; **NEW** 


5. 


DEC 


R2 


; **NEW** 


6. 


BEQ 


END 




7. 


CLR 


Rl 




8. 


INC 


R3 


; JM010 


9. 


MOV 


R2, NUMC 




10. 


CMPB 


(R0)+ # A 




11. 


BNE 


20$ 




12. 


BEQ 


10$ 


;BJ008 


13. 


INC 


Rl 





13.4.5 Temporarily Suppressing the Audit Trail 

You can temporarily suppress the generation of the audit trail by 
using the backslash (\) operator. You can then reenable audit-trail 
processing with the percent sign (%) operator. (You cannot enable 
audit trail processing with this operator if you have specified the 
/-AU switch in the SLP command line.) 
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Both operators are entered in the command input. The backslash (\) is 
specified in column 1 of the line that precedes those commands and/or 
input files for which you do not want audit-trail processing. The 
percent sign (%) is specified in column 1 of the line that precedes 
the lines for which you do want processing. For example: 

BAK . MAC ; 2 6/AU/-B F=B AK . MAC ; 2 5 

\ 

-2,2 

.IDENT /05.03/ 

-2 3, 23 

; VERSION 05.03 
-3 7, , 

; J. MATTHEWS ll-NOV-80 

; JM011 CORRECT OUT-OF-BOUNDS CONDITION FOR INPUT -BUFFER 

SIZE 

% 

-106, 106,/; JM011/ 

CMP #132., R3 ; IS INPUT -BUFFER SIZE IN RANGE? 

BLT 30$ ; IF LT, NO 



/ 

The lines between the backslash (\) and the percent sign (%) are not 
affected by audit-trail processing. The lines following the percent 
sign (%) are affected. 



13.4.6 Deleting the Audit Trail 

The /CM switch allows you to delete audit trails and trailing spaces 
and tabs from a file. The /CM switch applied to the output or input 
file specification accepts a numeric argument that specifies the 
beginning position of an audit trail or other text string to be 
deleted. The default for this argument is the position argument given 
for the /AU switch (or its default, decimal 80). This value is 
rounded to the next highest tab stop before use. 

When processing an input line, SLP first truncates the text to the 
next highest tab stop after the position specified, and then deletes 
any trailing spaces or tabs. The remaining text is copied to the 
output file. 

The /CM switch is specified in the form: 
/CM: [n] 

n 

A number designating the beginning character position of the 
audit trail (or other text) to be deleted. 

For example: 

SLP>SLPR11.MAC ; 12/CM :.ll 9 . =S LPR 1 1 . MAC ; 1 1 

/ 

In this case, the input lines are truncated to a length of 120(10) 
characters. The specified length is rounded up to the next highest 
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tab stop and the audit trail begins at column 121(10). Trailing 
spaces and tabs are deleted before each line is copied to the output 
file. 

In the following example, SLP truncates input lines to the default 
position of the audit trail, column 80(10). 

SLP>SLPR11.MAC ; 1 2=S LPR 1 1 . MAC ; 11 /CM 

/ 



13.5 SLP MESSAGES 

SLP messages are divided into two groups: information and error. The 
messages and suggested responses are given in the following sections. 
Section 13.5.1 describes the information message and Section 13.5.2 
describes the error messages. 



13.5.1 SLP Information Message 

SLP — COMMAND FILE CHECKSUM IS ###### 

Explanation: By specifying the /CS[:n] switch in the command 
line, you requested SLP to calculate the checksum value for the 
edit commands. 

User Action: This message is for your information only. No 
action is required. 



13.5.2 SLP Error Messages 

This section lists the SLP error messages. Following each message is 
an explanation of the error and recommended user action to correct the 
error . 

SLP error messages are issued in two formats: 

• SLP followed by a dash, the type of error message, and the 
error message. If applicable, the command line or command 
line segment that caused the message is printed on the next 
line. For example: 

SLP — *FATAL*-I LLEGAL SWITCH 
SHIRLEY. MAC ; 2/CF 

• SLP followed by a dash, the type of error message, the error 
message, and the name of the file with which the error is 
associated. For example: 

SLP — * FATAL* -OPEN FAILURE LINE LISTING FILE filename 

Note that all but two of the SLP error messages are fatal. The two 
exceptions are diagnostic messages, which are described at the end of 
this section. 
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SLP — * FATAL* -COMMAND SYNTAX ERROR 
command line 

Explanation: The command line format did not conform to syntax 
rules. Open files were closed and SLP was reinitialized. 

User Action: Reenter the command line, specifying the proper 
syntax . 



SLP — *FATAL*-I LLEGAL DEVICE NAME 
command line 

Explanation: The device specified was not a legal device. Open 
files were closed and SLP was reinitialized. 

User Action: Reenter the command line, specifying a legal 
device. 



SLP — *FATAL*-I LLEGAL DIRECTORY 
command line segment 

Explanation: The directory was not legally specified. Open 
files were closed and SLP was reinitialized. 

User Action: Reenter the command line, specifying a legal 
directory. 



SLP — *FATAL*-I LLEGAL ERROR/SEVERITY CODE pi p2 p3 

Explanation: This error message indicates an error in the SLP 
program. 

User Action: Reenter the command line. If the error persists, 
submit a Software Performance Report (SPR) with the console 
dialog and any other related information, such as programs or 
1 i stings . 



SLP — *FATAL*-I LLEGAL FILE NAME 
command line segment 

Explanation: A file specification was greater than 30(8) 
characters in length or contained a wildcard (that is, an 
asterisk in place of a file specification element) . Open files 
were closed and SLP was reinitialized. 

User Action: Reenter the command line, specifying a legal file 
name . 



SLP — *FATAL*-I LLEGAL GET COMMAND LINE ERROR 

Explanation: The system was unable to read a command line. This 
error message indicates an internal system failure or an error in 
the SLP program. 

User Action: Reenter the command line. If the error persists, 
submit a Software Performance Report (SPR) with the console 
dialog and any other related information. 
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SLP — *FATAL*-I LLEGAL SWITCH 
command line segment 

Explanation: The switch was not a legal SLP switch or a legal 
switch was used in an illegal manner. Open files were closed and 
SLP was reinitialized. 

User Action: Reenter the command line, specifying the legal 
switch. 



SLP — *FATAL*-INDIRECT COMMAND SYNTAX ERROR 
command line 

Explanation: The command line format specified for the indirect 
command file did not conform to syntax rules. Open files are 
closed and SLP was reinitialized. 

User Action: Reenter the command line, specifying the proper 
syntax . 



SLP — * FATAL*- INDIRECT FILE DEPTH EXCEEDED 
command line 

Explanation: More than three levels of indirect command files 
were specified in an indirect command file. Open files were 
closed and SLP was reinitialized. 

User Action: Correct the indirect command file and reenter the 
command line. 



SLP — *FATAL*-I/0 ERROR COMMAND INPUT FILE 
o r 

SLP — *FATAL*-I/0 ERROR COMMAND OUTPUT FILE 
o r 

SLP — *FATAL*-I/0 ERROR CORRECTION INPUT FILE filename 
or 

SLP — *FATAL*-I/0 ERROR LINE LISTING FILE filename 
or 

SLP — *FATAL*-I/0 ERROR SOURCE OUTPUT FILE filename 

Explanation: One of the following conditions may exist: 

• A problem exists on the physical device (for example, the disk 
is not spinning) . 

• The length of the command line was greater than the allowed 
number of characters. 

• The file is corrupted or the format is incorrect. 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 
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SLP — *FATAL*-INDIRECT FILE OPEN FAILURE 
command line 

or 

SLP — * FATA L*-0 PEN FAILURE CORRECTION INPUT FILE filename 
or 

SLP — * FATA L*-0 PEN FAILURE LINE LISTING FILE filename 
or 

SLP — *FATAL*-OPEN FAILURE SOURCE OUTPUT FILE filename 

Explanation: One of the following conditions may exist: 

• The file is protected against an access. 

• A problem exists with the physical device (for example, the 
device was not on-line) . 

• The volume is not mounted. 

• The specified file directory does not exist. 

• The named file does not exist in the specified directory. 

• The available Executive dynamic memory is insufficient for the 
operation . 

These errors cause open files to be closed and SLP to be 
reinitial ized . 

User Action: Determine which condition caused the message and 
correct that condition. Reenter the command line. 



SLP — *FATAL*-LINE NUMBER ERROR 
command line 

Explanation: The command line printed contained an illegally 
specified numeric line locator. 

User Action: Terminate the SLP edit session and refer to the 
rules for specifying numeric line locators in Section 13.3.1. 
Correct the error and reenter the command line. 



SLP — *FATAL*-PREMATURE EOF CORRECTION INPUT FILE filename 

Explanation: An out-of-range line locator was specified in an 
indirect command file or from the terminal; for example, -990 
was specified for an 800-line file. 

User Action: Terminate the current editing session. Restart 
the editing session, and enter the edit command line, specifying 
the correct line number. 
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SLP — *FATAL*-PREMATURE EOF COMMAND INPUT FILE 

Explanation: This is caused by not terminating SLP command input 

with a slash (/) or by inadvertently typing CTRL/Z at the 

terminal, which sends an end-of-file to SLP before the slash (/) 

character is read. SLP prompts (SLP>) , indicating that a new 
file specification is expected. 

User Action: Restart the editing session at the point where the 
CTRL/Z was typed. 



SLP — *DIAG*-ERROR IN COMMAND FILE filespec CHECKSUM 

Explanation: An incorrect value was specified for the command 
file checksum. If you enter the edit command lines directly from 
the terminal, the command file in the error message is CMI.CMD. 
Thus, the error message reads: 

SLP — *DIAG*-ERROR IN COMMAND FILE CMI.CMD CHECKSUM 

User Action: This is a warning message only. The specified 
output file is still created, although possibly not as intended. 



SLP — *DIAG*-n LINES TRUNCATED BY AUDIT TRAIL 
command line 

Explanation: Line truncation by the audit trail was detected. 

User Action: This is an informational message only. The 
specified output file is still created. (In the listing file, a 
question mark (?) replaces the period (.) in the line number of 
the lines that were truncated. It is possible that audit-trail 
strings from the input file will be truncated by the new 
audit-trail string although text strings will not be truncated.) 
Determine where the truncation (s) occurred. If necessary, modify 
the command file so that it contains commands that do not cause 
truncation . 
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CHAPTER 14 
OBJECT MODULE PATCH UTILITY (PAT) 



The Object Module Patch Utility (PAT) allows you to update, or patch, 
code in a relocatable binary object module. 

Input to PAT is two files, an input file and a correction file. The 
input file consists of one or more concatenated object modules. You 
can correct only one of these object modules with a single execution 
of PAT. The correction file consists of object code that, when linked 
by the Task Builder, either overlays or is appended to the input 
object module. Unlike the Task Builder and ZAP patching options, PAT 
allows you to increase the size of the object module because the 
changes are applied before the module is linked by the Task Builder. 

PAT uses the correction file, which contains corrections and/or 
additional instructions, to update the object module. Correction 
input is prepared in source form and then assembled by the MACRO-11 
assembler . 

Output from PAT is the updated input file. 

You invoke PAT using any of the methods for invoking a utility 
described in Chapter 1. PAT can be used interactively or by means of 
indirect command files. If you use indirect command files, PAT allows 
a maximum nesting level of 2. 

Using PAT to update a file involves several steps. First, you create 
the correction file using a text editor. Once created, the correction 
file must be assembled to produce an object module. The correction 
file and the input file (both in object module format) are then 
submitted to PAT for processing. Finally, the updated input object 
module is submitted to the Task Builder to resolve global symbols and 
to create an executable task. Figure 14-1 shows the processing steps 
involved in generating an updated task file using PAT. 



14.1 SPECIFYING THE PAT COMMAND LINE 

Specify the PAT command line in the following format: 

[outf ile] =inf ile[/CS [:number] ] ,correctf ile[/CS: [number] ] 
outf ile 

The file specification for the output file. If you do not 
specify an output file, PAT does not generate one. 
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inf ile 



The file specification for the input file. This file can contain 
one or more concatenated object modules. 



correctf ile 



The file specification for the correction file. This file 
contains the updates to be applied to one module in the input 
file. 



/CS[: number] 



Specifies the Checksum switch. This switch directs PAT to 
calculate the checksum for all the binary data that constitutes 
the module. PAT displays this checksum in octal. (Refer to 
Section 14.2.4 for information on how to use /CS.) You can 
optionally specify an octal number with /CS. Then, after PAT 
calculates the checksum value, it compares that value with the 
number you specified. If the values are not the same, PAT 
informs you with an error message. You must then rerun PAT, 
specifying the correct checksum. 



CORRECT.SRC 



TEXT 
EDITOR 



Generate a correction file using 
the Text Editor. 



CORRECT.SRC 



CORRECT.OBJ 



Execute the assembler (or compiler) 
to generate an object module 
version of the file. 



CORRECT.OBJ 



MYFILE.OBJ 



MYFILE.OBJ 



3. Execute PAT using as input the 
/ correction file and the module to 

be updated. 



o 



MYFILE.OBJ 



TASK 
BUILDER 



MYFILE.TSK 



4. Execute the Task Builder to 
resolve new addresses and 
generate an executable task. 



ZK- 199-81 



Figure 14-1 Processing Steps Required to Update a 
Module Using PAT 
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14.2 HOW PAT APPLIES UPDATES 

This, section describes the PAT input and correction files, gives 
information on how to create the correction file, and gives examples 
of how PAT applies the corrections to a module. 



14.2.1 The Input File 

The input file is the file to be updated; it is the base for the 
output file. The input file must be in object module format. When 
you execute PAT, the correction file is applied to one of the object 
modules in the file. PAT assumes a file type of .OBJ for the input 
file. If you use a file type other than .OBJ, you must specify it 
explicitly in the command line. 



14.2.2 The Correction Pile 

The correction file contains the patches to be applied to the input 
file. PAT assumes a file type of .OBJ for the correction file. If 
you use a file type other than .OBJ, you must specify it explicitly in 
the command line. 

As shown in Figure 14-1, the first step in using PAT to update an 
object file is to generate the correction file. Use any text editor 
to create this source file, which is usually in the following format: 

.TITLE inputname 
. I DENT updatenum 
inputl ine 
inputl ine 



inputname 

The name of the module to be corrected by the PAT update. You 
must specify the module that you are updating for inputname. 

updatenum 

Any value acceptable to the MACRO-11 .IDENT assembler directive. 
Generally, this value reflects the updated version of the file to 
be processed by PAT (as shown in the examples given in Section 
14. 2. 3) . 



NOTE 

The .IDENT assembler directive is a 
required part of the correction file. 
Failure to include an .IDENT directive 
in the file produces unusable output. 



inputl ine 

Lines of input to be used to correct and update the input file. 

Once you have created the source version of the correction file, you 
assemble it to produce an object module that can be processed by PAT. 
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During PAT execution, new global symbols defined in the correction 
file are added to the module's symbol table. A symbol definition that 
is already being used in the input file can be superseded by the 
definition in the correction file. For a symbol definition to be 
superseded, both definitions must be either relocatable or absolute. 

A duplicate program section supersedes the previous program section, 
provided : 

• Both have the same relocatabil ity attribute (ABS or REL) 

• Both are defined with the same directive (.PSECT or .CSECT) 

If PAT encounters duplicate program section names, the length 
attribute for the program section is set to the length of the longer 
program section and a new program section is appended to the module. 

If you specify a transfer address, it supersedes the transfer address 
of the module being patched. 



14.2.3 How PAT and the Task Builder Update Object Modules 

The examples in the following sections show an input file and a 
correction file (both in object module format) to be processed by PAT 
and the Task Builder, along with a source-like representation of how 
the output file looks once PAT and the Task Builder complete 
processing. Two techniques are described: one for overlaying lines 
in a module and the other for adding a subroutine to a module. 



14.2.3.1 Overlaying Lines in a Module - The following example 
illustrates a technique using a patch file to overlay lines in a 
module. First, PAT appends the correction file to the input file. 
Then, the Task Builder generates a task image from the patched object 
modules . 

The input file for this example is: 

.TITLE ABC 
.IDENT /01/ 

ABC: : 

MOV A,C 
CALL XYZ 
RETURN 
. END 

To add the instruction ADD A,B after the CALL instruction, you can use 
the following patch in the correction file: 

.TITLE ABC 

. IDENT /01. 01/ 

.=.+12 

ADD A , B 

RETURN 

. END 
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You use the MACRO-11 assembler to assemble the correction file. After 
assembly, PAT processes the resulting object module and the input 
object module. The result of PAT processing appears as follows: 



ABC 



. =ABC 
.=.+12 



.TITLE ABC 

.IDENT /01.01/ 

MOV A,C 

CALL XYZ 
RETURN 



ADD A, B 

RETURN 

. END 



You then use the Task Builder to produce the patched object module as 
a task image. This task image looks the same as the source code would 
have looked if it had originally been written as follows: 



ABC 



. TITLE 


ABC 


. IDENT 


/01. 01/ 


MOV 


A,C 


CALL 


XYZ 


ADD 


A, B 


RETURN 




. END 





PAT uses the .=.+12 in the program counter field to determine where to 
begin overlaying instructions in the program. It overlays the RETURN 
instruction with the patch code: 



ADD A, B 
RETURN 



14.2.3.2 Adding a Subroutine to a Nodule - The second example 
illustrates a technique for adding a subroutine to an object module. 
A patch often requires that more than a few lines be added to correct 
the file. A convenient technique for adding new code is to append it 
to the end of the module as a subroutine. That way, you insert a CALL 
instruction at an appropriate location in the subroutine. The CALL 
instruction directs the program to branch to the new code, execute 
that code, and then return to in-line processing. 



The input file for this example is: 



ABC 



.TITLE ABC 

.IDENT /01/ 

MOV A, B 

CALL XYZ 

MOV C,R0 
RETURN 



. END 
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The correction file for this example is: 



PATCH: 



.TITLE 


ABC 


. IDE NT 


/01. 01/ 


CALL 


PATCH 


NOP 




. PSECT 


PATCH 


MOV 


A, B 


MOV 


D, R0 


ASL 


RO 


RETURN 




. END 





PAT merges the correction file with the input file, as in the first 
example. The Task Builder then processes the files and produces a 
task image that looks the same as the source file would have looked if 
it had originally been written as follows: 



ABC: : 



.TITLE ABC 
.IDENT /01.01/ 



CALL 

NOP 

CALL 

MOV 

RETURN 



PATCH 

XYZ 
C, RO 



PATCH: 



.PSECT PATCH 



MOV 
MOV 
ASL 
RETURN 
. END 



A, B 

D,R0 

RO 



In this example, the CALL PATCH and NOP instructions overlay the 
3-word MOV A, B instruction. (The NOP is included because this is a 
case where a 2-word instruction replaces a 3-word instruction and NOP 
is required to maintain alignment.) The Task Builder allocates 
additional storage for .PSECT PATCH, writes the specified code into 
this program section, and binds the CALL instruction to the first 
address in this section. The MOV A, B instruction, replaced by the 
CALL PATCH instruction, is the first instruction executed by the PATCH 
subroutine . 



14.2.4 Determining and Validating the Contents of a File 

You use the Checksum switch (/CS) to determine or validate the 
contents of a module. The switch directs PAT to calculate the 
checksum (in octal) for all the binary data that constitutes the 
module and to then inform you of the checksum by means of a diagnostic 
message . 

To determine the checksum of a file, enter the PAT command line with 
the /CS switch applied to that file's specification. For example: 

=MYFILE/CS, CORRECT. POB 
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The command directs PAT to calculate the checksum for the input file, 
MYFILE. PAT then responds with the message: 

INPUT MODULE CHECKSUM IS checksum 

PAT generates a similar message when you request the checksum for the 
correction file. For example: 

=MYFILE, CORRECT. POB/CS 

After calculating the checksum for the correction file, PAT responds 
with the message: 

CORRECTION INPUT FILE CHECKSUM IS checksum 

If you specify /CS:number to validate the size of a file, PAT 
calculates the checksum for the file and then compares that checksum 
with the value you specified as number. If the two values do not 
match, PAT displays the following message to report the checksum 
error : 

ERROR IN FILE filename CHECKSUM 

For example, you might specify: 

=MYFILE, CORRECT. POB/CS: 432163 

When PAT calculates the checksum for the correction file, the number 
is different. PAT then displays the message: 

ERROR IN FILE CORRECT. POB CHECKSUM 

Checksum processing always results in an octal, nonzero value. 

14. 3 PAT MESSAGES 

PAT generates messages that state checksum values and messages that 
describe error conditions. For checksum values and nonfatal error 
messages, PAT prefixes the messages with: 

PAT — *DIAG*-error message 

For messages that describe fatal errors (errors that caused PAT to 
terminate), PAT uses the prefix: 

PAT — *FATAL*-er ror message 

The following messages are grouped according to message type, as 
follows: 

• Information messages 

• Command line errors 

• File specification errors 

• Input/Output errors 

• File content or format errors 

• Internal software error 

• Storage allocation error 
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14.3.1 Information Messages 

The following messages describe results of checksum processing. 

CORRECTION INPUT FILE CHECKSUM IS checksum 

Explanation: When you specify /CS in the correction file 
specification, PAT informs you of the file's checksum value. The 
value is given in octal. 

User Action: No response necessary. 

INPUT MODULE CHECKSUM IS checksum 

Explanation: When you specify /CS in the input file 
specification, PAT informs you of the file's checksum value. The 
value is given in octal. 

User Action: No response necessary. 



14.3.2 Command Line Errors 

The following error messages result from failure to adhere to the 
command line syntax rules. 

COMMAND LINE ERROR command line 

Explanation: The system standard command line processor ( . GCML) 
detected an error in the command line. 

User Action: Reenter the command line using the correct 
information . 

COMMAND SYNTAX ERROR command line 

Explanation: The command line contained a syntax error. 

User Action: Reenter the command line using the correct syntax. 



ILLEGAL INDIRECT FILE SPECIFICATION command line 

Explanation: You specified an indirect command file that 
contains one of the following errors: 

• A syntax error 

• A specification for a nonexistent indirect command file 

User Action: Check for file specification syntax errors or 
ensure that the specified file is contained in the specified User 
File Directory. Reenter the command line. 
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MAXIMUM INDIRECT FILE DEPTH EXCEEDED command line 

Explanation: In the command line, you specified an indirect 
command file that exceeds the maximum nesting level of 2 that is 
permitted by PAT. 

User Action: Reorder your files so that they do not exceed PAT's 
nesting limit. 



14.3.3 File Specification Errors 

The following error messages are caused by errors in the specification 
of input or output files or related file switches. 

CORRECTION INPUT FILE MISSING command line 

Explanation: The mandatory correction file was not specified. 

User Action: Reenter the command line specifying the correction 
file. 

ILLEGAL DEVICE/VOLUME SPECIFIED device name 

Explanation: The device or volume name specification contained a 
syntax error. 

User Action: Check the rules for specifying devices and volumes, 
then reenter the command line using the correct syntax for the 
device or volume specification. 

ILLEGAL DIRECTORY SPECIFICATION directory name 

Explanation: The directory specification contained a syntax 
error . 

User Action: Check the rules for specifying a directory and 
reenter the command line using the correct syntax for the 
directory specification. 

ILLEGAL FILE SPECIFICATION filename 

Explanation: The file specification contained a syntax error. 

User Action: Reenter the command line using the correct syntax 
for the file specification. 

ILLEGAL SWITCH SPECIFIED filename 

Explanation: An unrecognized switch or switch value was 
specified with the file. 

User Action: Check the rules for specifying the switch and 
reenter the command line using the correct switch or switch 
value . 
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INVALID FILE SPECIFIED filename 

Explanation: You specified a file that contains one of the 
following errors: 

• Nonexistent device 

• Nonexistent directory - The directory in the filename 
specification does not exist on the specified device (or on 
the default device if no device was specified) . 

User Action: Reenter the command line specifying the correct 
device or directory. 

MULTIPLE OUTPUT FILES SPECIFIED command line 

Explanation: PAT accepts only one output file specification. 

User Action: Reenter the command line specifying only one output 
f ile . 



REQUIRED INPUT FILE MISSING command line 

Explanation: The mandatory input file was not specified in the 
command line. 

User Action: Reenter the command line specifying an input file. 

TOO MANY INPUT FILES SPECIFIED command line 

Explanation: Too many input files were specified in the command 
line. PAT accepts only the input and correction file 
specifications. 

User Action: Reenter the command line specifying the correct 
files . 



UNABLE TO FIND FILE filename 

Explanation: PAT could not locate the specified input or 
correction file. 

User Action: Check the directory to ensure that the file exists. 
Reenter the command line specifying the correct filename. 



14.3.4 Input/Output Errors 

The following error messages are caused by faults detected while PAT 
was performing I/O to the specified file. 
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ERROR DURING CLOSE: FILE: filename 

Explanation: This error is most likely to occur while PAT is 

attempting to write the remaining data into the output file 

before deaccessing it. The most likely causes of this error are 
the following conditions: 

• The device is full 

• The device is write-locked 

• A hardware error occurred 

User Action: Perform the appropriate corrective action and 
reenter the command line: if the device is full, delete all 
unnecessary files; if the device is write-locked, write-enable 
it; if the problem is a hardware error, contact your DIGITAL 
Field Service representative. 



ERROR POSITIONING FILE filename 

Explanation: PAT attempted to position the file beyond 
end-of-file. 

User Action: Submit a Software Performance Report along with the 
related console dialog and any other pertinent information. 



I/O ERROR ON INPUT FILE filename 

Explanation: An error was detected while PAT was attempting to 
read the specified input file. The principal cause of this error 
is a device hardware error. 

User Action: Reenter the command. 



I/O ERROR ON OUTPUT FILE filename 

Explanation: An error occurred while PAT attempted to write into 
the named output file. The most likely causes of this error are 
the following conditions: 

• The device is full 

• The device is write-locked 

• A device hardware error occurred 

User Action: Perform the appropriate corrective action and 
reenter the command line: if the device is full, delete all 
unnecessary files; if the device is write-locked, write-enable 
it; if the problem is a hardware error, contact your DIGITAL 
Field Service representative. 



14.3.5 Errors in File Contents or Format 

The following errors represent inconsistencies detected by PAT in the 
format or contents of the input or correction files. 
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ERROR IN FILE filename CHECKSUM 

Explanation: The checksum that PAT calculated for the named file 
does not match the one that you specified with /CS:number. 

User Action: Ensure that you specified the correct checksum. If 
the checksum is correct, then you specified an invalid version of 
the file. Rerun PAT specifying the correct version of the file. 



FILE filename HAS ILLEGAL FORMAT 

Explanation: The format of the named file is not compatible with 
the object files produced by the standard DIGITAL language 
processors or accepted by the Task Builder. The principal causes 
are : 

• Truncated input file 

• Input file that consists of text 

User Action: Ensure that the file is in the correct format and 
resubmit it for PAT processing. 



INCOMPATIBLE REFERENCE TO GLOBAL SYMBOL symbol name 

Explanation: The correction file contains a global symbol whose 
attributes do not match one or more of the following input file 
symbol attributes: 

• Definition or reference 

• Relocatable or absolute 

User Action: Update the correction file by modifying the symbol 
attributes. Reassemble the file and resubmit it for PAT 
processing . 



INCOMPATIBLE REFERENCE TO PROGRAM SECTION section name 

Explanation: The correction file contains a section name whose 
attributes do not match one or both of the following input file 
section attributes: 

• Relocatable or absolute 

• Defined with the same directive (.PSECT or .CSECT) 

User Action: Update the correction file by modifying the section 
attribute or changing the section type. Reassemble the file and 
resubmit it to PAT for processing. 
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UNABLE TO LOCATE MODULE module name 

Explanation: PAT could not find the module name that was 
specified in the correction file in the file of concatenated 
input modules. 

User Action: Update the input file specification to include the 
missing module. Reenter the command line. 



14.3.6 Internal Software Error 

This error reflects internal software error conditions. 



ILLEGAL ERROR -SEVERITY CODE error data 

Explanation: An error message call, containing an illegal 
parameter, has been generated. 

User Action: If these messages persist, submit a Software 
Performance Report along with related console dialog and any 
other pertinent information. 



14.3.7 Storage Allocation Error 



The following error message indicates that not enough task memory was 
available for storing global symbol and program section data. 



NO DYNAMIC STORAGE AVAILABLE storage-1 isthead 

Explanation: Not enough contiguous task memory was available to 
satisfy a request for the allocation of storage. 

PAT displays the contents of the 2-word dynamic storage 1 isthead 
in octal. 



User Action: If possible, PAT should be reinstalled with a 

larger increment or in a bigger partition. (See the description 

of the INSTALL command in the RSX- 11M/M-PLUS MCR Operations 
Manual . ) 
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CHAPTER 15 
TASK/FILE PATCH PROGRAM (ZAP) 



The Task/File Patch Program (ZAP) allows you to directly examine and 
modify task image and data files on a Files-11 volume. Using ZAP, you 
can patch these files interactively without reassembling and 
rebuilding the task. 

ZAP supports four types of task image files: 

• Regular task image files, which include those mapped to 
resident and supervisor mode libraries 

• Multiuser task image files 

• I- and D-space (instruction and data space) tasks 

• Resident libraries 

Note that only RSX-11M-PLUS supports tasks mapped to supervisor mode 
libraries, multiuser tasks, and I- and D-space tasks. 

These types of task image files are discussed fully with the /List 
switch (Section 15.1.1). 

ZAP performs many of the functions performed by the RSX-11 on-line 
debugging utility, ODT. Thus, working knowledge of ODT is helpful in 
using ZAP. See the IAS/RSX-11 ODT Reference Manual for more 
information on ODT. 

ZAP provides the following features: 

• Operating modes that allow you to access specific words and 
bytes in a file, modify locations in a file, list the disk 
block and address boundaries for each overlay segment in a 
task image file on disk, and open a file for reading only 

• A set of internal registers that include eight Relocation 
Registers 

• Single-character commands that, with other command line 
elements, allow you to open and close locations in a file and 
to display and manipulate the values in those locations 

Except in read-only mode, the results of ZAP commands are permanent. 
Thus, the best way to use ZAP is with a hard-copy terminal so that you 
have a record of the changes you make. 

Although the ZAP program is relatively straightforward to use, 
patching locations in a task image file requires knowing how to use 
the map (or memory allocation file) generated by the Task Builder and 
the listings generated by the MACRO-11 assembler. These maps and 
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listings provide information you need to access the locations whose 
contents you want to change. For information on Task Builder maps, 
see the RSX-11M/M-PLUS Task Builder Manual . For information on 
MACRO-11 listings, see the PDP-11 MACRO- 11 Language Reference Manual . 



15.1 ZAP OPERATING MODES AND SWITCHES 

ZAP provides two addressing modes and two access modes. The 

addressing modes are task image mode and absolute mode. Task image 

mode is the default mode. The access modes are read/write mode and 

read-only mode. Read/write is the default mode. Either addressing 

mode can be used with either access mode. The modes and their 
associated switches are as follows: 

• Task image mode is the default addressing mode for ZAP. In 
this mode, addresses in ZAP command lines refer to addresses 
in the task image file as they are shown in the Task Builder 
map for the file. See Section 15.2 for more information on 
using task image mode. 

• In absolute mode, specified with the /AB switch, ZAP processes 
the addresses you enter in ZAP command lines as absolute byte 
addresses within the file. You must use absolute mode for any 
files that are not task images. See Section 15.2 for more 
information on using absolute mode. 

• Read/write mode is the default access mode for ZAP. In this 
mode, ZAP opens a file for reading and/or modification. 

• In read-only mode, specified with the /RO switch, ZAP opens a 
file for reading but not modification. That is, you can 
execute ZAP functions that change the contents of locations, 
but these changes are not actually made to the file. When ZAP 
exits, the original values in the file are still there. 



15.1.1 The List Switch (/LI) 

When using ZAP in task image mode (but not absolute) , you can also 
specify the /List switch (/LI) . The /List switch directs ZAP to 
display the overlay segment table for the task image file on disk that 
you are working with. The table lists the starting disk block and 
address boundaries for each overlay segment in the file. The segment 
table lists are in a different format for each type of task image 
file. (The formats are discussed later in this section.) You use this 
table and the Task Builder map to locate the task segments being 
changed . 

The /LI switch displays the overlay segment boundaries in the 
following format: 

I ssssss: aaaaaa-bbbbbb [nnnnnn] [dddddd] 

ssssss : 

The starting block in octal, 
aaaaaa 

The lower address boundary in octal. 
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bbbbbb 

The upper address boundary in octal, 
nnnnnn 

The segment name that appears for I- and D-space tasks; manually 
loaded overlays ($LOAD) ; memory-resident overlays; tasks that 
link to the library with memory-resident overlays; or for any 
combination of the previous conditions. 

dddddd 

The description of the segment type string which appears next to 
the segment name in the segment table. 

The following sections describe the /List switch formats for the 
different kinds of task image files. Section 15.7 gives examples of 
the segment table lists. 
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15.1.1.1 The /LI Switch and Regular Task Image Files - For 

regular task image files (including those mapped to resident and 
supervisor mode libraries), the /LI switch displays the task's overlay 
segments in the order of their location in the file. Each segment in 
these files begins on an even block boundary. 



15.1.1.2 The /LI Switch and Multiuser Task Image Files 

For multiuser tasks, the /LI switch lists the starting disk block 
number and address boundaries of each segment. In addition, the 
address boundaries of the shared read-only segment are listed. The 
block number that is used to reference the multiuser segment is the 
same as the root segment. The multiuser segment is an extension of 
the root segment. The segment list disk block numbers have a 
corresponding entry in the Task Builder map. 

See the RSX-11M/M-PLUS Task Builder Manual for more information on 
multiuser tasks. 



15.1.1.3 The /LI Switch and Resident Libraries - For resident 
libraries, the /LI switch displays each of the task's segments as 
beginning on a new block boundary. However, the segments may not 
actually begin on even boundaries because of compression by the Task 
Builder. Resident libraries can be overlaid, but each overlay segment 
must also be resident in memory. 

To avoid the possibility that two or more segments in a single block 
could have the same virtual address, ZAP treats the resident library 
in the same way that the Task Builder does. The Task Builder builds 
the library with each segment beginning on an even block boundary, but 
then compresses the segments in the task file itself. The Task 
Builder map is generated before the segments are compressed, so the 
boundaries given in the map do not necessarily correspond to the 
actual location of the segments. 

The disk block boundaries given in the Task Builder map file are the 
ones that ZAP uses to address locations in the resident library and 
that the /LI switch displays in its segment table. They do not use 
the actual starting blocks of the segments. (You should be aware of 
this when you are working with resident libraries in absolute mode. 
However, also remember that you cannot use the /LI switch in absolute 
mode . ) 

You should also note that ZAP cannot know the physical starting 
addresses for the segments of an overlaid resident library because its 
overlay structure is stored in the symbol definition (.STB) file, not 
with the task image file itself. For ZAP, each segment's starting 
address is 000000. 

See the RSX-11M/M-PLUS Task Builder Manual for more information on 
res ident libraries. 



15.1.1.4 The /LI Switch and I- and D-Space Tasks - For I- and D-space 
tasks, the /LI switch lists the starting block number and the address 
boundaries of each segment. The I-space or D-space segment may be 
suppressed in the listing when, for example, a segment with only 
I-space code does not include a listing for a D-space segment. If the 
segments are not suppressed, the segment list disk block numbers have 
a corresponding entry in the Task Builder map. 
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15.2 ADDRESSING LOCATIONS IN FILES 

To address locations in a file, ZAP provides two addressing modes 
(task image and absolute, described above) and a set of internal 
registers, which includes eight Relocation Registers. This section 
first introduces the concept of relocation biases and the use of the 
Relocation Registers, then explains how to use the addressing modes. 



15.2.1 Relocation Biases 

When MACRO-11 generates a relocatable object module, the base address 
of each program section of the module is 000000. In the assembler 
listing, all locations in the program section are shown relative to 
this base address. 

The Task Builder links program sections to other program sections by 
mapping the relative addresses applied by the assembler to the 
physical addresses in memory (for unmapped systems) or to virtual 
addresses (for mapped systems) . 

Many values within the resulting task image are biased by a constant 
whose value is the absolute base address of the program section after 
the section has been relocated. This bias is called the relocation 
bias for the program section. 

ZAP 1 s eight Relocation Registers, OR through 7R, are generally set to 
the relocation biases of the program sections to be examined. This 
allows you to refer to a location in a module by the same relative 
address that appears in the MACRO-11 listing. The addressing modes 
help you calculate the relocation biases. 



15.2.2 ZAP Addressing Modes 

As explained in Section 15.1, ZAP's 
in a file are task image mode and 
the default mode for ZAP. The next 
these modes. 



two modes for addressing locations 
absolute mode. Task image mode is 
two sections explain how to use 



The following examples show excerpts from a MACRO-11 listing of the 
module MYFILE and a Task Builder map. These excerpts and the 
accompanying text show how to use ZAP in task image mode. The 
following lines represent assembled instructions from a MACRO-11 
source listing: 



71 000574 

72 000602 

73 000604 

74 000610 

75 000614 

76 000620 

77 000624 



032767 
001002 
000167 
016700 
016000 
010067 
032760 



000000G 000000G 

000406 
000000G 
000000G 
177534 

000000G 000000G 



BIT #FE.MUP,$FMASK 

BNE 2$ 

JMP 30$ 

2$: MOV $TKTCB,R0 

MOV T.UCB(RO) ,R0 

MOV R0,UCB 

BIT #U2.HLD,U.CW2 (R0) 



The following lines from a Task Builder map give the information you 
need to address locations in the task image file as they appear in the 
above MACRO-11 listing: 
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R/W MEM LIMITS: 120000 123023 003024 01556. 
DISK BLK LIMITS: 000002 000005 000004 00004. 

MEMORY ALLOCATION SYNOPSIS: 

SECTION TITLE IDENT FILE 

. BLK. : (RW,I,LCL,REL,CON) 120232 0025*46 01382. 

120232 002244 01188. MYFILE 01 MCR.OLB 
122476 000064 00052. FMTDV 01 MCR.OLB 

$$RESL: (RW, I,LCL,REL, CON) 123000 000024 00020. 

Using information in the Task Builder map, you can determine the block 
number and byte offset for the beginning of the file you want to 
change. The disk-block-limits line lists block 2 as the block where 
the program code begins. The synopsis lists byte offset 120232 as the 
beginning of the file MYFILE. To address location 574 in the MACRO-11 
listing in task image mode, specify the following command line: 

2: 120232+574/© 

ZAP responds by opening the location and displaying its contents: 

002:121026/ 032767 
Section 15.4 describes the ZAP command line formats. 



15.2.2.1 Using the Task Image Addressing Mode - In task image mode, 
ZAP allows you to address locations in a task image file by using the 
addresses the MACRO-11 assembler displays in its listing and the 
starting block number and byte offset listed in the Task Builder map. 
Unlike absolute mode, task image mode is useful for working with 
locations in an overlaid file because the Task Builder and ZAP perform 
the calculations necessary to relate the file's disk structure to its 
run-time memory structure. 



15.2.2.2 Using the Absolute Addressing Mode - In absolute mode, ZAP 
processes the addresses you enter in the command lines as absolute 
byte addresses within the file. To use ZAP in absolute mode, invoke 
ZAP and enter the /AB switch with the file specification. 

ZAP interprets the first address in the file you are changing as 
virtual block 1, location 000000. All other addresses you enter are 
interpreted using this address as the base location. Absolute mode 
allows you to access all the bytes in a data or task image file as 
well as the label and header blocks of a task image file on disk. 
However, to modify a disk task image, you must know the disk layout of 
the task image. Generally, absolute mode is practical only for data 
files or for task image files that are not overlaid. 



15.3 INVOKING AND TERMINATING ZAP 

You invoke ZAP using any of the methods described in Chapter 1. 
However, you cannot enter a file specification on the same line that 
you use to invoke ZAP unless the file is an indirect command file (see 
Section 15.3.1). 
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When ZAP prompts you, enter the file specification for the file you 
want to change. You enter the file specification in the format: 

dev : [uf d] filename .f iletype ; vers ion [/sw. . . ] 

The default file type is . TSK. After you enter the file 
specification, ZAP prompts with an underscore (_) . 

You terminate ZAP by entering the X command (explained in Section 
15.6.1). This command exits you from ZAP and returns control to your 
command line interpreter. 



15.3.1 Using Indirect Command Files with ZAP 

An indirect command file contains the specification for the file you 
want to work with and the appropriate ZAP commands. You can specify 
the indirect command file in the same command line in which you invoke 
ZAP. 

The following sample indirect command file (called CHANGE . CMD) 
contains ZAP commands. The commands will change the default priority 
of the despooler from 70 to 80 (120 octal). The V command (explained 
in Section 15.6.5) is used to verify that 70 (106 octal) is what is 
actually in the location to be changed. The command file has the 
following ZAP commands: 

LPP.TSK/AB 

0: 346/ 

106V 

120 

X 

To use the indirect command file (in this case, from MCR) , type the 
following : 

>ZAP ^CHANGE 

This command invokes ZAP, which then executes the commands in the 
file. 

The commands being used first open the task image file (LPP.TSK) in 
absolute mode (/AB) . The next two commands open the desired location 
(byte 346 in block 0) and verify its contents (106) . The next command 
changes the contents to 120, which will be the new default priority 
for the despooler. The X command exits you from ZAP and returns 
control to MCR. 



15.4 THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS 

ZAP commands perform functions that allow you to examine and modify 
the contents of locations in a file. Command lines comprise 
combinations of the following elements: 

• Commands 

• Internal registers 
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• Arithmetic operators 

• Command line element separators 

• The current location symbol 

• Location-specifier formats 

The command elements can be combined to perform multiple functions. 
The function of a given command line depends not only on which 
elements you use, but also on the position of one element in relation 
to the next. 



The following sections describe 
Sections 15.5 and 15.6 describe 
elements to execute ZAP functions. 



the ZAP command line elements, 
how to combine the command line 



15.4.1 ZAP Commands 

There are three types of ZAP commands: 

• Open/close location commands 

• General purpose commands 

• RETURN Key 

The following sections describe each type of command. 



15.4.1.1 Open/Close Location Commands - Open/close location commands 
are nonalphanumer ic ASCII characters that direct ZAP to perform a 
sequence of functions. Open/close commands specify two general 
sequences of operations: 

• Open a location, display its contents, and store the contents 
in the Quantity Register (see Section 15.4.2) 

• Close the location after (optionally) modifying it and open 
another location as specified by the command 

Section 15. 5 describes the format for specifying open/close location 
commands . 



15.4.1.2 General Purpose Commands - ZAP provides six 

single-character, general purpose commands. You use these commands 
for calculating displacements, verifying location contents, and 
exiting from ZAP. You can enter some of the commands on the command 
line with no other parameters. Section 15.6 describes the format for 
specifying these commands. 



15.4.1.3 RETURH Key - Unless there is another value or command on the 
line, the RETURN key closes the current location as modified and opens 
the next sequential location. ZAP commands take effect only after you 
press the RETURN key. 
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15.4.2 ZAP Internal Registers 

ZAP internal registers are fixed storage locations that ZAP uses as 
registers. These registers contain values set by both you and ZAP. 
ZAP provides the following internal registers: 

• Relocation Registers through 7 (OR through 7R). These 
registers provide a means for indexing into a program section 
to change the contents of locations in the program section. 
You load the registers with the base address of the program 
section that has been relocated by the Task Builder. 

• The Constant Register (C) . You set this register to contain a 
16-bit value, which you can specify as an expression in the 
ZAP command line. 

• The Format Register (F) . This register controls the format of 
the displayed address. If the value of the F Register is 
(the initial value) , ZAP displays addresses relative to the 
largest value of any Relocation Register whose value is less 
than or equal to the address to be displayed. If the value of 
the Format Register is not 0, ZAP displays addresses in 
absolute byte format. 

• The Quantity Register (Q). ZAP sets the value in the register 
to be the last value displayed at your terminal. 

To access the contents of a register, specify a dollar sign ($) 
preceding the register name (in this case, C) in the command line. 
For example: 

$C/ (RET) 

$C/ 00000 



This command line directs ZAP to display the contents of the Constant 
Register. The slash (/) is an open command described in Table 15-3. 



15.4.3 ZAP Arithmetic Operators 

Operators are single-character command line elements that define an 
arithmetic operation. Generally, ZAP evaluates these expressions as 
addresses. Table 15-1 describes the operators. 

You use the operators in expressions in command lines. For example, 
rather than manually adding all the displacements listed in the Task 
Builder map, you can specify a location using the following notation: 

_2: 120000+170/© 

This method for calculating such a displacement is faster and more 
accurate than doing it manually. 
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Table 15-1 
ZAP Arithmetic Operators 



Operator 


Function 


+ 


The plus sign adds a value to another value. Used in 
an expression that ZAP then evaluates to be a command 

1 inp p] ampnt- _ 




The minus sign subtracts a value from another value. 
Used in an expression that ZAP then evaluates to be a 
command line element. 


* 


The asterisk multiplies a value by 50(8) and adds it 
to another value. Used to form a Radix-50 string. 



The following example shows how to use the asterisk (*) to form 
Radix-50 strings. Section 15.4.4 explains the use of the colon and 
comma; the percent sign is an open command described in Table 15-3. 

_0, 40/© 

002:0,000040/ 000001 

_i *3 3 m 

/m 

1502: 0, 000040/ 000103 
002:0,000040% A$ 

In this example, the first command opens the locations that is 40 
bytes offset from the location address contained in Relocation 
Register and displays in octal format the contents of the new 
location. The location contains the value 000001. The second command 
converts 000001 to Radix-50 and adds 33 to the Radix-50 value. The 
slash (/) command again displays in octal the value contained in the 
offset location. The value is now 103. The percent sign (%) command 
displays 103 in Radix-50 format. 



15.4.4 ZAP Command Line Element Separators 

ZAP provides separators to delimit one command line element from 
another. Different separators are required depending on the type of 
ZAP command being executed. See Table 15-2. 



Table 15-2 
ZAP Command Line Element Separators 



Separator 



Function 



The comma separates a Relocation Register 
specification from another command line element. 

The semicolon separates an address from an internal 
register specification. Used in expressions that set 
values for Relocation Registers. 

The colon separates a block number base value from a 
byte offset into the block. Used in most of the 
references to locations in a file. 



15-9 



TASK/FILE PATCH PROGRAM (ZAP) 



15.4.5 ZAP Command Line Location-Specifier Formats 

ZAP has three formats for specifying locations in a command line. 
Each provides a means of indexing into a file. The formats are: 

• Current location symbol 

• Byte offset 

• Block number :byte offset 

• Relocation reg ister ,byte offset 



15.4.5.1 The Current Location Symbol - In command line expressions 
that ZAP evaluates as addresses, a period (.) represents the last open 
location . 



15.4.5.2 Byte Offset Format - You specify the byte offset format as 
follows : 

location 

If you are using ZAP in absolute mode, ZAP interprets this 
specification as a byte offset from block 1, location 000000. This 
format is generally useful only when you are using absolute mode. 

The following ZAP command line opens absolute location 664 and 
displays its contents in octal format: 

664 / (riD 



15.4.5.3 Block NumberrByte Offset Format - This format allows you to 
specify a byte offset from a specific block in the file. Specify the 
format as follows: 

blocknum :byteof f set 

You can use this format for addressing locations whether or not you 
enter the /AB switch with the file specification. 

In task image mode, ZAP allows you to enter the block number and byte 
offset displayed in the Task Builder map. The map gives information 
on the overlay segments in a task image file. See Section 15.2 for 
more information. 



15.4.5.4 Relocation Register , Byte Offset Format - This format allows 
you to load a Relocation Register with the address of a location. The 
address is then used as a relocation bias. You specify this format 
for addressing locations in a task image file as follows: 

relocreg ,byteof f set 

Specify relocreg in the form nR, where n is the number of the 
Relocation Register. You can then address byte offsets from the 
address loaded in the Relocation Register. For example: 
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_2: 001254; 3R(H) 
_3,64/m 

002:3,000064/ 037334 

The first command loads the address 001254 into Relocation Register 3, 
then the second command opens the location that is 64 bytes offset 
from block 2, location 001254. The contents of that location are 
037334. 



15.5 USING ZAP OPEN AND CLOSE COMMANDS 

This section gives examples of how to use the ZAP open and close 
commands. These commands allow you to open locations in a file, 
modify those locations, and close the locations. 

Table 15-3 summarizes the open and cflose commands. 



Table 15-3 
ZAP Open and Close Commands 



Character 


Designation 


Function 


/ 


Slash 


Opens a location, displays its 
contents in octal, and stores the 
contents of the location in the 
Quantity Register (Q). If the 
location is odd, it is opened as a 
byte . 


n 


Quotation mark 


Opens a location, displays the 
contents of the location as two ASCII 
characters, and stores the contents of 
the location in the Quantity Register 
(Q). 


% 


Percent sign 


Opens a location, displays the 
contents of the location in Radix-50 
format, and stores the contents of the 
location in the Quantity Register (Q). 


\ 


Backslash 


Opens a location as a byte, displays 
the contents of the location in octal, 
and stores the contents of the 
location in the Quantity Register (Q). 


i 


Apostrophe 


Opens a location, displays the 
contents as one ASCII character, and 
stores the contents of the location in 
the Quantity Register (Q). 



(continued on next page) 
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Table 15-3 (Cont.) 
ZAP Open and Close Commands 



Character 


Designation 


Function 


m 


RETURN Key 


Closes the current location as 
modified and opens the next sequential 
location if no other values or 
commands are on the command line. ZAP 
commands take effect only after you 
press the RETURN key. 




Circumflex or 
Up-arrow 


Closes the currently open location as 
modified and opens the preceding 
location . 




Underscore or 
Back-arrow 


Closes the currently open location as 
modified, uses the contents of the 
location as an offset from the current 
location and opens the new location. 


e 


At sign 


Closes the currently open location as 
modified, uses the contents of the 
location as an absolute address, and 
opens that location. 


> 


Right angle 
bracket 


Closes the currently open location as 
modified, interprets the low-order 
byte of the contents of the location 
as the relative branch offset and 
opens the target location of the 
branch . 


< 


Left angle 
bracket 


Closes the currently open location as 
modified, returns to the location from 
which the last series of underscore 
( ) , at sign (@) , and/or right angle 
bracket (>) commands began, and opens 
the next sequential location. 



15.5.1 Opening Locations in a File 

Use any of the ZAP open commands — slash (/) , quotation mark ("), 
percent sign (%), backslash (\) , or apostrophe (') — to open a 
location in a file. The format ZAP uses to display the contents of 
the open location depends on which operator you use. 

Once you open a location in a given format, ZAP displays in that 
format any other locations you open. For example, if you enter the 
percent sign (%) command, the contents of the open location are 
displayed in Radix-50 format. If you continually press the RETURN 
key, consecutive locations are displayed in Radix-50 format until you 
change the format by entering a different special-character open 
command . 
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15.5.2 Changing the Contents of a Location 

When you open a location with a special-character open command, you 
can change the contents of that location by entering the new value and 
pressing the RETURN key. The following example is a sequence of 
commands and ZAP responses that shows how to open a location, change 
the value of the location, and close the location. 

_/m 

002: 120000/ 000000 
_44444© 

/m 

IT02: 120000/ 44444 

The first command (/) displays in octal format the contents (000000) 
of the current location. The contents are changed by entering the 
value 44444 and then the location is closed as modified by pressing 
the RETURN key. The slash (/) and RETURN key display the new contents 
of the location (last line of example). 



15.5.3 Closing Locations in a File 

ZAP uses the RETURN key and other special-character commands for 

closing a location in a file. The close commands perform three 
functions : 

• Close the current location 

• Direct ZAP to another location (such as the preceding location 
or a location referred to by the current location) 

• Open the new location 

The following sections give examples of how each command works. 



15.5.3.1 Closing a Location and Opening the Preceding Location 
Use the circumflex (~) or up-arrow (+) command (depending on the type 
of terminal you are using) to close the current location, to direct 
ZAP to the preceding location, and to open that location. The 
following sequence of ZAP commands and responses shows how this 
command works: 

_2: 120100/© 

002: 120100/ 000000 

_m 

002: 120102/ 000111 

m 

002: 120104/ 000222 

_m 

002: 120106/ 000333 

002: 120104/ 000222 

The RETURN key closes the first three open locations and then opens 
the next location. The circumflex command closes location 120106 and 
directs ZAP to open the preceding location, 120104. 



15-13 



TASK/FILE PATCH PROGRAM (ZAP) 



15.5.3.2 Closing a Location and Opening an Offset Location - Use 
the underscore (_) or back-arrow ( ) command to close the current 
location, to direct ZAP to use the contents of the current location as 
an offset from the current location, and to open the new location. 
The following sequence of ZAP commands and responses shows how this 
command works: 

_2: 12 0100/© 
002:120100/ 000000 

•RET) 

002: 120102/ 111111 

(RET) 

302:120104/ 222222 

(RET) 

002: 120106/ 000022 

(SET) 

002: 120132/ 123456 

The RETURN key closes the first three open locations. The underscore 
command closes location 120106, directs ZAP to use the contents (22) 
of the current location as the offset from the current location 
(120110), and then opens that offset location (120132). 



15.5.3.3 Closing a Location and Opening an Absolute Location - Use 
the at sign (@) command to close the current location, to direct ZAP 
to use the contents of the just-closed location as the absolute 
address of a location, and to open that location. The following 
sequence of ZAP commands and responses shows how this command works: 

_2: 120100/(1!) 
002:120100/ 000000 

jm 

002:120102/ 111111 
002:120104/ 120114 

_@(RET) 

002:120114/ 114114 

The RETURN key closes the first three open locations. The at sign 
command closes 120104, directs ZAP to use the contents (120114) of 
that location as the absolute address of the next location to open, 
and then opens that location. 



.15.5.3.4 Closing a Location and Opening a Branch Target Location - 
Use the right angle bracket (>) command to close the current location, 
to direct ZAP to use the low-order byte of the contents of the 
just-closed location as a branch offset for the address of the next 
location, and then to open that location. The following sequence of 
ZAP commands and responses shows how this command works: 

_2: 120100/di; 

002: 120100/ 005000 

(RED 

002: 120102/ 005301 

_m 

002: 120104/ 001020 

_> <m 

002: 120146/ 052712 
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The RETURN key closes the first three open locations. The right angle 
bracket command closes location 120104, directs ZAP to use the 
low-order byte (020) of its contents as the branch offset for the 
address of the next location (120146), and then opens that location. 



15.5.3.5 Closing a Location and Opening a Previous Location - Use the 
left angle bracket (<) command to close the current location; to 
direct ZAP to the location where -the current series of underscore (_) , 
at sign (@) , and/or right angle bracket (>) commands began; and then 
to open that location. The following sequence of ZAP commands and 
responses shows how this command works: 

_1202; OR© 

0, 10/(15 
002:0,000010/ 005212 

_m 

T502: 0, 005224/ 001020 

_> m 

002:0,005266/ 000000 
002: 0, 000000/ 000000 

_<: (SED 

002:0,000012/ 000430 

The underscore command directs ZAP to location 005224. The right 
angle bracket command directs ZAP to location 005266, and the at sign 
command directs ZAP to location 000000. The left angle bracket 
command then directs ZAP to location 000012, which is the next 
sequential address after the location where the sequence of commands 
began . 



15.6 USING ZAP GENERAL PURPOSE COMMANDS 

This section explains the functions of ZAP general purpose commands 
and shows the formats for specifying them. Table 15-4 describes the 
commands . 



Table 15-4 
ZAP General Purpose Commands 



Command 


Function 


X 


Exits from ZAP; returns control to your command line 
interpreter 


K 


Calculates the offset in bytes between an address and 
the value contained in a Relocation Register, 
displays the offset value, and stores it in the 
Quantity Register (Q) 





Displays the jump and branch displacements from the 
current location to a target location 




Displays in octal the value of the expression to the 
left of the equal sign 


V 


Verifies the contents of the current location 


R 


Sets the value of a Relocation Register 
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15.6.1 The X Command 

Use the X command to exit from ZAP and then return control to your 
command line interpreter. 

Specify the X command in the format: 

X 



15.6.2 The K Command 

Use the K command to calculate the offset in bytes between an address 
and the value contained in a Relocation Register, to display the 
offset value, and to store it in the Quantity Register (Q). 

You can enter the K command in the following formats: 

K Calculates the offset in bytes between the address of the 

currently open location and the value of the Relocation 
Register whose contents are equal to or closest to (but less 
than) the value of that address 

nK Calculates the offset in bytes between the currently open 

location and Relocation Register n 

a;nK Calculates the offset in bytes between address a and 

Relocation Register n 

ZAP responds to the K command by displaying the Relocation Register it 
used and the offset value it calculated in the format: 

=reg ,of f set 

The following example shows how to use the K command: 

_2: 1172; OR© 
2: 1232, -IRE) 
~2: 1202/ m 
002:000020/ 000111 

_k m 

=0, 000010 
_0, 100; IK © 
=1, 000040 

The first command sets the value of Relocation Register to 001172. 
The second command sets the value of Relocation Register 1 to 001232. 
The slash command displays in octal format the contents of location 
001202 (000111). The K command calculates the physical distance 

(offset) between the address of the currently open location (001202) 
and the value of the Relocation Register whose contents are equal to 
or closest to (but less than) the value of the address. ZAP then 
displays the number of the Relocation Register it used (0) and the 
offset (00010=001202-001172). The last command adds 100 to the 
address in Relocation Register (001172) and then calculates the 
offset between the new address (001272) and the contents of 
Relocation Register 1 (001232). ZAP then displays the number of the 
specified Relocation Register (1) and the offset 

(000040=001272-001232) . 
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15.6.3 The Command 

Use the command to display the jump and branch displacements from 
the current location to a target location. A jump displacement is the 
offset between the open location and the target location. The jump 
displacement is used in the second word of a jump instruction if the 
instruction uses relative addressing. A branch displacement is the 
low-order byte of a branch instruction which, when executed, branches 
to the target location. 

You can enter the command in the following formats: 

aO Displays the jump and branch displacements from the current 

location to the target of the branch (a) 

a;rO Displays the jump and branch displacements from location a 

to target location r 

The following example shows how to use the command: 

_0, 4534/© 
0,4534/ 1234 

45660 m 

000030> 000014 
~4534; 45660 m 
~000030> 000014 

The first number (000030) is the jump displacement; the second number 
(000014) is the branch displacement. 



15.6.4 The Equal Sign (=) Command 

Use the equal sign command (=) to display (in octal) the value of the 
expression to the left of the equal sign. 

Specify the equal sign command in the format: 

expression= 

The following example shows how to use the equal sign command (note 
that 177777 equals -1): 

_2: 30/© 

002:000030/ 000000 
_. +177756= m 
000006 

The first command displays in octal format the contents of location 
000030, which are 000000. The next command adds 177756 to the address 
of the currently open location (000030). ZAP then displays the value 
of the specified expression (6=30+177756 or 6=30-22). 



15.6.5 The V Command 

Use the V command to verify that a location contains a specified 
value . 

Specify the V command in the format: 
contentsV 
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You use the V command to ensure that, before you have ZAP change them, 
the contents being changed are what they should be. The V command is 
mainly useful in indirect command files because ZAP issues an error 
message and exits if the contents do not match. That way, the 
contents are not changed incorrectly. 

The following example shows how to use the V command; if you were 
using an indirect command file, you would include this sequence of ZAP 
commands in it. 

0, 1200/ 

6V 

10 

ZAP opens the location that is 1200 offset from the value of 
Relocation Register and ensures that the value contained at the 
location is 6. If so, ZAP changes the 6 to 10. If the value is not 
6, ZAP exits. 



15.6.6 The R Command 

Use the R command to specify the value for a Relocation Register. As 
explained in Sections 15.2 and 15.4.2, ZAP uses these registers to 
index into a program section so that you can change the contents of 
locations in the program section. 

Specify the R command in the format: 

__contents ;nR 

The variable n is the number of the Relocation Register (0 through 7). 
For example: 

$3R/ (TO 
$3R/ 177777 
_1 25670; 3R © 

$3R/ (RETS 
$3R/ 125670 

The first command accesses the contents of Relocation Register 3, 
which ZAP displays in octal format as specified by the slash. The 
contents of the register are 177777. The next command changes the 
contents of the register to 125670. The last command again displays 
the contents of the register, which have been changed correctly. 



15.7 EXAMPLES 

This section gives examples of ZAP usage. The examples show the /LI 
switch segment table format and how you would use some of the ZAP 
commands. 

All of the ZAP examples in this section are based on information 
contained in the following excerpts from a sample Task Builder memory 
allocation map and from the program code for some of the modules in 
the task. Each example follows the section of program code associated 
with it. 
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Excerpts from Task Builder map: 
MAINMEO . TSK; 1 



Memory allocation map TKB M40.10 
14-MAR-83 16:01 

. . .MEO 

GEN 
MOO 

[31,102] 



Page 1 



Task name 
Partition name 
Identification 
Task UIC 

Stack limits: 000300 001277 001000 00512. 
PRG xfr address: 020520 
Task attributes: ID 
Total address windows: 2. 

Task image size : 9184. words, I-Space 

3520. words, D-Space 

Task Address limits: 000000 043647 I-Space 

000000 015507 D-Space 

R-W disk blk limits: 000002 000102 000101 00065. 

MAINMEO. TSK;1 Overlay description: 



Base 


Top 


Length 






000000 


023135 


\J £» J X O \J 


09822. 


I 


MAINO 


000000 


014123 


014124 


06228. 


D 




022140 


043645 


021506 


09030. 


I 


INPUT 


014124 


015507 


001364 


00756. 


D 




022140 


022307 


000150 


00104. 


I 


CALC 


014124 


014167 


000044 


00036. 


D 




022310 


022437 


000130 


00088. 


I 


AADD 


014170 


014173 


000004 


00004. 


D 




022310 


022437 


000130 


00088. 


I 


SUBB 


014170 


014173 


000004 


00004. 


D 




022310 


022437 


000130 


00088. 


I 


MULL 


014170 


014173 


000004 


00004. 


D 




022310 


022441 


000132 


00090. 


I 


DIVV 


014170 


014173 


000004 


00004. 


D 




022140 


023725 


001566 


00886. 


I 


OUTPUT 


014124 


014251 


000126 


00086. 


D 




MAINMEO. 


TSK;1 


Memory 


allocation 


map TKB 


MAINO 




14 


-MAR-8 3 




16:01 


*** Root 


segment 


: MAINO 








R/W mem 


1 imi ts : 


000000 


023135 


023136 0982: 



Page 2 



000000 014123 014124 06228. D-Space 

Disk blk limits: 000002 000024 000023 00019. I-Space 
000025 000041 000015 00013. D-Space 
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Memory allocation synopsis: 

Section Title Ident File 

. BLK. : (RW,I,LCL,REL,CON) 000300 000216 00142. 

000300 000216 00142. CBTA 04.3 SYSLIB . OLB ; 7 



MAINMEO. TSK; 1 Memory allocation map TKB M40.10 Page 4 

INPUT 14-MAR-83 16:01 

*** Segment: INPUT 

R/W mem limits: 022140 043645 021506 09030. I-Space 
014124 015507 001364 00756. D-Space 

Disk blk limits: 000042 000063 000022 00018. I-Space 
000064 000065 000002 00002. D-Space 



Page 5 

*** Segment: CALC 

R/W mem limits: 022140 022307 000150 00104. I-Space 
014124 014167 000044 00036. D-Space 

Disk blk limits: 000066 000066 000001 00001. I-Space 
000067 000067 000001 00001. D-Space 



Page 7 

*** Segment: AADD 

R/W mem limits: 022310 022437 000130 00088. I-Space 
014170 014173 000004 00004. D-Space 

Disk blk limits: 000070 000070 000001 00001. I-Space 
000071 000071 000001 00001. D-Space 



Page 8 

*** Segment: SUBB 

R/W mem limits: 022310 022437 000130 00088. I-Space 
014170 014173 000004 00004. D-Space 

Disk blk limits: 000072 000072 000001 00001. I-Space 
000073 000073 000001 00001. D-Space 
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Page 9 

*** Segment: MULL 

R/W mem limits: 022310 022437 000130 00088. I-Space 
014170 014173 000004 00004. D-Space 

Disk blk limits: 000074 000074 000001 00001. I-Space 
000075 000075 000001 00001. D-Space 



MAINMEO. TSK; 1 Memory allocation map TKB M40.10 Page 10 

DIW 14-MAR-83 16:01 

*** Segment: DIW 

R/W mem limits: 022310 022441 000132 00090. I-Space 

014170 014173 000004 00004. D-Space 

Disk blk limits: 000076 000076 000001 00001. I-Space 

000077 000077 000001 00001. D-Space 



*** Segment: OUTPUT 

R/W mem limits: 022140 023725 001566 00886. 

014124 014251 000126 00086. 

Disk blk limits: 000100 000101 000002 00002. 

000102 000102 000001 00001. 

Memory allocation synopsis: 

Section 
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I-Space 
D-Space 

I-Space 
D-Space 



Title Ident File 



BLK. : (RW f I ,LCL,REL,CON) 



022140 


000374 


00252. 






022140 


000042 


00034. 


SAVAL 


00 


022202 


000074 


00060. 


CATB 


03 


022276 


000126 


00086. 


CDDMG 


00 


022424 


000110 


00072. 


C5TA 


02 



SYSLIB.OLB;7 
SYSLIB.OLB;7 
SYSLIB.OLB;7 
SYSLIB.OLB;7 



Example 1: 

In this example, the segment table for task MAINMEO is requested. 
Note that the segment table corresponds exactly to the overlay 
description list given in the Task Builder map. The sequence of ZAP 
commands is as follows: 



15-20.1 



April 1983 



TASK/FILE PATCH PROGRAM (ZAP) 



>ZAP(H) 

ZAP>MAINMEO/LI (SET] 

ZAP Version V02.01 COPYRIGHT (c) DIGITAL EQUIPMENT CORPORATION 1983 



Segment Table 








000002 


f\ f\ A A A rt 

: 000000- 


022137 


MAI NO 


I-space root 


00002 5 


f\ /\ A A A A 

000000- 


01412 j 


MAI NO 


D— space root 


000042 


: 022140- 


043647 


INPUT 


I- and 


000064 


014124- 


015507 


INPUT 


D-space 


000066 


: 022140- 


022307 


CALC 


I- and 


000067 


014124- 


014167 


CALC 


D-space 


A A A A T A 

000070 


A O *"k 1 A 

. 022310- 


022347 


A ADD 


I- and 


000071 


014170- 


U 1 4 1 / o 


a a r\r* 


D— space 


000072 


022310- 


022437 


SUBB 


I- and 


000073 


014170- 


014173 


SUBB 


D-space 


000074 


022310- 


022437 


MULL 


I- and 


000075 


014170- 


014173 


MULL 


D-space 


000076 


022310- 


022443 


DIVV 


I- and 


000077: 


014170- 


014173 


DIVV 


D-space 


000100 


022140- 


023727 


OUTPUT 


I- and 


000102 


014124- 


014253 


OUTPUT 


D-space 



In Example l r the first command line invokes ZAP and the second 
command line requests the segment table for the task MAINMEO. The 
/List switch directs ZAP to give the starting disk block for the root 
segment of the task (in this example, MAIN0) and for each segment 
overlaid on the root of the task. The /List switch also lists the 
base and top addresses, plus the segment text string for each segment. 

Because this is an I- and D-space overlaid task, there is an I-space 
root segment and a D-space root segment and each is a part of the root 
segment of the task MAIN0. In this example, the I-space root segment 
begins at disk block 2. The addresses for the I-space root segment 
range from 000000 to 022137. The next line of numbers is for the 
D-space root segment which begins at disk block 25. The addresses for 
the D-space root segment range from 000000 to 014123. The next line 
of numbers is for the segment INPUT. That I-space segment begins at 
disk block 42 and the D-space segment begins at disk block 64. The 
I-space addresses range from 022140 to 043647 and the D-space 
addresses range from 014124 to 015507. The table continues for the 
remaining overlaid segments in the task MAINMEO. 

Example 2: 

In this example, the contents of a location in another task module 
(TEST. MAC) are being changed. The following excerpt from the module 
shows the associated code. 



TEST 


- TEST 


MACRO FILE MACRO 


M1113 18-MAR 


-81 07:48 PAGE 8-1 


1269 








; THIS IS A 


PART OF THE MODULE 


1270 










TEST. MAC 


1271 








; WHICH IS 


IN THE ROOT SEGMENT: 


1272 










TEST 


1273 












1274 


010132 


010146 




MOV 


R1,-(SP) 


1275 


010134 


012704 


041114 


MOV 


#"LB,R4 


1276 


010140 


005003 




CLR 


R3 


1277 


010142 






CALL 


$FNDUB 


1278 


010146 


010146 




MOV 


R1,-(SP) 


1279 


010150 


012704 


050123 


MOV 


#"SP,R4 
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The first command line invokes ZAP and the second command line 
requests the segment table for TST. The /List switch gives the 
starting disk block for the root task and for each task overlaid to 
the root task. The switch also lists the base and top addresses for 
each of the tasks. 

In this example, TEST (the root task) begins at disk block 42 and its 
addresses range from 120000 to 151513. The next line of numbers is 
for the task module TSTC1.MAC. That task begins at disk block 74 and 
its addresses range from 151514 to 153133. The table continues for 
the remaining tasks. 

Example 2: 

In this example, the contents of a location in another task module 
(TEST. MAC) are being changed. The following excerpt from the module 
shows the associated code. 

TEST - TEST MACRO FILE MACRO M1113 18-MAR-81 07:48 PAGE 8-1 

1269 ; THIS IS A PART OF THE MODULE 

12 70 ; TEST. MAC 

1271 ; WHICH IS IN THE ROOT SEGMENT: 

12 72 ; TEST 

12 73 



1274 


010132 


010146 




MOV 


R1,-(SP) 


1275 


010134 


012704 


041114 


MOV 


#"LB,R4 


12 76 


010140 


005003 




CLR 


R3 


1277 


010142 






CALL 


$FNDUB 


1278 


010146 


010146 




MOV 


R1,-(SP) 


1279 


010150 


012704 


050123 


MOV 


# M SP,R4 



The sequence of ZAP commands is: 

_42: 121244; OR© 

0, 10136"© 
(542: 131402" LB 

_• m 

042:131402' L 
_' m 

042:131403' B 

_120 dD 

_o, 10136" m 

042:131402" LP 

The first command line loads the starting address of TEST. MAC (121244 
in disk block 42) into Relocation Register 0. The second command line 
displays as an ASCII word the contents of location 10136 of the 
module. The contents are LB. The first apostrophe command (') 
displays the first byte of the word (L) and the second command 
displays the second byte (B) . The following command line changes the 
contents of the second byte to 120, which is the ASCII code for the 
letter P. The last command displays the new contents of location 
10136, which are now LP. 

Example 3: 

In this example, the contents of a location are also being changed. 
This time, the location is in the module TSTVB1.MAC. The following 
excerpt is the associated code. 
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TSTVB1 - TSTVB1 MACRO FILE MACRO M1113 18-MAR-81 07:52 PAGE 4-2 



153 
154 
155 
156 
157 
158 
159 
160 



000334 
000336 
000340 
000346 



005702 
001404 
052767 
000403 



PART OF MODULE TSTVBl.MAC 
WHICH IS ALSO IN THE ROOT SEGMENT: 
TEST 



000060 172516 



TST 
BEQ 
BIS 
BR 



R2 
70$ 

#60,SR3 
75$ 



The sequence of ZAP commands is: 



_42: 133470; 1R<RET> 

1, 342/<RET> 
042:134032/ 000060 
_100<RET> 

1, 342/<RET> 
042:134032/ 000100 



The first command line loads the starting address of TSTVBl.MAC 
(133470 in disk block 42) into Relocation Register 1. The second 
command line displays in octal the contents of location 342 in the 
module. The third command line changes the contents of this location 
from 60 to 100. The last command line displays the new contents 
(again in octal ) . 

Example 4: 

In this example, the operation code (op code) for one of the 
instructions in another module is being changed. The module is 
TSTCM.MAC, and the following excerpt is the associated code. 

TSTCM - TSTCM MACRO FILE MACRO M1113 18-MAR-81 07:47 PAGE 3-7 



402 
403 
404 

405 001272 073127 177766 

406 001276 010037 00000G 

407 001302 062701 140002 



PART OF THE MODULE TSTCM.MAC 

WHICH IS IN THE SEGMENT: TSTCM 

ASHC #-10., Rl 

MOV R0,@#KISAR6 

ADD #140000+2, Rl 



The sequence of ZAP commands is: 



_113: 154530;R2 m 

_2, 1302/ m 

113:156032/ 062701 

_162 701 

2 , 1302/ (RET) 

113:156032/ 162701 
_X 

The first command line loads the starting address of TSTCM.MAC (154530 
in disk block 113) into Relocation Register 2. The second command 
line displays in octal the current instruction contained in location 
1302. The instruction includes the op code 06 for the ADD operation. 
The third command line changes the op code to 16, which signifies the 
SUBTRACT operation. The fourth command line displays the new contents 
of the location and the X command ends the ZAP session. 
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15.8 ZAP ERROR MESSAGES 

This section lists the messages generated by ZAP, explains the 
condition that causes each message, and suggests a response to the 
message . 



ZAP — ADDRESS NOT WITHIN SEGMENT 

Explanation: The address specified was 
segment specified. 

User Action: Reenter the command line, 
address or overlay segment number. 



ZAP — CANNOT BE USED IN BYTE MODE 

Explanation: The at sign (@) , underscore (_) , and right angle 
bracket (>) commands cannot be used when a location is opened as 
a byte. 

User Action: If the location is an even address, open the 
location as a word. 



ZAP — ERROR IN FILE SPECIFICATION 

Explanation: The file specification was entered incorrectly. 

User Action: Reenter the command line, using the correct file 
specification. 



ZAP -- ERROR ON COMMAND INPUT 

Explanation: An I/O error occurred while a command line was 
being read. This could be a hardware error. 

User Action: Ensure that the hardware is functioning properly. 
If it is, reenter the command line. If not, call your DIGITAL 
Field Service representative. 



ZAP — I/O ERROR ON TASK IMAGE FILE 

Explanation: An I/O error occurred while the file being modified 
was being read or written. This could be a hardware error. 

User Action: Ensure that the hardware is functioning properly. 
If it is, reenter the command line. If not, call your DIGITAL 
Field Service representative. 



ZAP — NO OPEN LOCATION 

Explanation: You attempted to modify the contents of a closed 
location . 

User Action: Open the location to perform the modification. 



not within the overlay 



specifying the correct 
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ZAP — NO SUCH INTERNAL REGISTER 

Explanation: The character following a dollar sign was not a 
valid specification for the internal register. 

User Action: Reenter the command line, specifying the correct 
value . 



ZAP ~ NO SUCH RELOCATION REGISTER 

Explanation: An invalid number was specified for a Relocation 
Reg ister . 

User Action: Relocation Registers are numbered through 7. Any 
other numbers are illegal. Reenter the command line, specifying 
a valid Relocation Register number. 



ZAP — NO SUCH SEGMENT 

Explanation: The starting disk block was not the start of any 
segment in the task image file on disk. 

User Action: Reenter the command line, specifying the correct 
disk block address. 



ZAP — NOT A TASK IMAGE OR NO TASK HEADER 

Explanation: An error occurred while the segment tables were 
being constructed. Possibly, the file is not a task image, the 
/AB switch was not specified, or the task image is defective. 

User Action: Terminate the ZAP session, then try invoking ZAP 
with the /AB switch specified. 



ZAP — NOT IMPLEMENTED 

Explanation: You entered a command that is recognized by ZAP, 
but not implemented. 

User Action: Ensure that you entered the command correctly. 



ZAP — OPEN FAILURE FOR TASK IMAGE FILE 

Explanation: The file to be modified could not be opened. 
Possibly, the file does not exist, the file is locked, the device 
is not mounted, or you do not have write-access to the file. 

User Action: Check the file specification for errors; ensure 
that the volume is properly mounted; or use PIP to check your 
file access privileges (see Chapter 3). 
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ZAP — SEGMENT TABLE OVERFLOW 

Explanation: ZAP does not have enough room in its partition to 
construct a segment table. 

User Action: Install ZAP in a larger partition or with a larger 
address space. (See the description of the INSTALL command in 
the RSX-11M/M-PLUS MCR Operations Manual or the RSX-11M/M-PLUS 
Command Language Manual . ) 



ZAP — TOO MANY ARGUMENTS 

Explanation: You entered more arguments on the command line than 
are allowed. 

User Action: Reenter the command line, specifying the correct 
syntax . 



ZAP — UNRECOGNIZED COMMAND 

Explanation: ZAP did not recognize the command as entered. 

User Action: Check the syntax of the command you are trying to 
execute, then reenter the command line, specifying the correct 
syntax . 



ZAP — VERIFY FAILURE 

Explanation: The V command determined that the contents of a 
location did not match the expected value. ZAP terminates. 

User Action: If applicable, check for errors in the indirect 
command file. Ensure that the contents of the file are what they 
should be. Locate the cause of the error and reenter the command 
line. Ensure that you are correcting the right file or file 
version . 
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APPENDIX A 
COMMANDS AND SWITCHES 

A.l INTRODUCTION 

This appendix presents a summary of the commands and switches used by 
the RSX-11M/M-PLUS utilities described in this manual. Each section 
number of the appendix corresponds to the chapter discussing that 
utility. For example, Chapter 3 and Section A. 3 both deal with PIP. 

Commands and switches are presented alphabetically within the sections 
of this appendix, regardless of their presentation in the various 
chapters. 

A. 2 EDI COMMAND SUMMARY 

Add string 

Adds the text specified by string to the end of the current line. 
AP string 

Same as ADD, except that the new current line is printed. 

Beg in 

Sets the current line to the line preceding the top line of the 
block buffer or input file. 

BLock[ON] or [OFF] 

Switches text access modes. 

BO [TTOM] 

Sets the current line pointer to the bottom of the block buffer 
or input file. 

[n] Change /st r ingl/string2 [/] 

Replaces stringl with string2 n times in the current line 

CLose [filespec] 

Transfers the remaining lines in the block buffer and the input 
file into the output file, then closes both the input file and 
the output file. If filespec is given, the output file is 
renamed . 
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CLOSES 

Closes the secondary input file. 
CDL [filespec] 

Same as the CLOSE command, except that the input file is deleted. 
CC [character] 

Changes the command concatenation character to the specified 
character (the default is &) . 

gfRL/Z) 

Closes files and terminates the editing session. 

Delete [n] or [-n] 

Deletes the current and next n-1 lines, if n is positive; 
deletes n lines preceding the current line, but not the current 
line, if n is negative. [-n] is valid in block mode only. 

DP [n] or [-n] 

Same as DELETE, except that the new current line is printed. 

End 

Same as the BOTTOM command. 
ERASE [n] 

Erases the current line or the block buffer and the next n-1 
blocks . 

m 

Prints the previous line, makes it the new current line, and 
exits from input mode (block mode only) . <ESCAPE> is the same as 
NP-1. 

EXit [filespec] 

Closes files, renames the output file, and terminates the editing 
session . 

EDx [filespec] 

Transfers remaining lines in block buffer and input file to 
output file, and closes the file. If filespec is given, the 
output file is renamed. The command then deletes the input file 
and terminates the editing session. 

FF 

Inserts a form feed into the block buffer (used to delimit a 
page) . 

File filespec 

Transfers lines from the input file to both the output file and 
the file specified by filespec. 
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[n]Find [string] 

Finds the line starting with string or, if n is specified, the 
nth line starting with string. 

INsert [string] 

Inserts string immediately following the current line. If string 
is not specified, EDI enters input mode. 

KILL 

Closes the input and output files, and deletes the output file. 

[n]LC /stringl/string2 [/] 

Changes all occurrences of stringl in current line and n-1 lines 
to string2. 

List 

Prints on the user terminal all lines remaining in the block 
buffer or input file, starting with the current line. 

LP 

Lists the text in the block buffer or input file on the pseudo 
device CL: , starting with the current line. 

[n] Locate string 

Searches for string or, if n is specified, the nth occurrence of 
string. In block mode, the search stops at end of the current 
block . 

MACRO x definition 

Defines macro number x to be definition. The value x may be 1, 
2, or 3. 

MCall 

Retrieves macro definitions stored in the file MCALL;n. 
[n]Mx [a] 

Executes macro x for n times, passing it the numeric argument a. 

[n] <def inition> (MACRO IMMEDIATE) 

Allows you to define and execute a macro n times in one step. 
The macro is stored as macro number 1. 

Next [n] or [-n] 

Establishes a new current line plus or minus n lines from the 
current line. 

NP [n] or [-n] 

Same as NEXT command, except that the new current line is 
printed . 
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OPens filespec 

Opens the specified secondary input file. 

OUtput [ON] or [OFF] 

Continues or discontinues writing to output file (line-by-line 
mode) . 

Overlay [n] 

Deletes the current line and the next n-1 lines, enters input 
mode, and inserts new lines as typed in place of original lines. 

PAGe [n] 

Enters block mode, if not already in block mode, and reads page n 
into the block buffer. 

[n]PFind (string) 

Searches successive block buffers until the nth occurrence of 
string is found. The string must begin in column 1. 

[n]PLocate (string) 

Searches successive block buffers for the nth occurrence of 
string. The string can occur anywhere in the line. 

PAste /stringl/string2 [/] 

Same as the LINE CHANGE (LC) command, except that all lines in 
the remainder of the block buffer or input file are searched for 
stringl. Wherever found, stringl is replaced with string2. 

Print [n] 

Prints the current line and the next n-1 lines. The last line 
printed becomes the current line. 

REAd [n] 

Reads the next n blocks of text into the block buffer. 
RENew [n] 

Writes the current block to the output file and reads new block n 
from the input file (block mode only) . 

m 

Prints the next line, makes it the current line, and exits from 
input mode. Pressing the RETURN key is the same as NP+1. 

Retype string 

Replaces the current line with the text of string. If string is 
not specified, the line is deleted. 

SAve [n] [filespec] 

Saves the current line and the next n-1 lines in the file 
specified by filespec. If filespec is not given, the lines are 
saved in SAVE.TMP. 
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SC /stringl/string2 [/] 

Locates stringl and replaces it with string2. 

SP 

Reestablishes the primary file as the input file. 

SS 

Selects the secondary file that will be the input file. 
SIZE n 

Specifies the maximum number of lines to be read into the block 
buffer . 

TAb [ON] or OFF 

Turns automatic tabbing on or off. 

Top 

Same as BEGIN command. 

TOF 

In block mode, returns to the top of the input file and saves all 
pages edited. TOF reads in a new block after writing the 
previous block to the output filer. 

TYpe [n] 

Prints next n lines. Same as PRINT command in line-by-line mode. 
In block mode, the current line pointer does not change unless 
EOB is reached. 

UNSave [filespec] 

Inserts all lines from the specified file following the current 
line. If filespec is not given, SAVE.TMP is used. 

UC [ON] or OFF 

Turns uppercase conversion of lowercase characters on or off. 
Verify [ON] or OFF 

Specifies whether locator and change commands are verified. 

Write 

Writes the contents of the current block buffer to the output 
file and then erases the block buffer. 

A. 3 PIP COMMAND SUMMARY 

outfile=infilel[,infile2... ,inf ilen] /AP [/FO] 

Opens an existing file (outfile) and appends the input file(s) to 
the end of it. (/FO is the File Owner subswitch.) 
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outf ile/BS:n= inf ilel [. . . , inf ilen] 

Defines the block size for magnetic tapes. 



outfile=infilel[,infile2...,infilen][ [/ME] [/subswi tch (es) ] ] 

Creates a copy of a file on the same or another device. The /ME 
(Merge) switch creates a new file from two or more existing 
files. Subswi tches are one or more of the following: 



/BL: n [ . ] Block allocated 

/CO Contiguous output 

/-CO Output can be noncontiguous 

/FO File Owner 

/NV New Version 

/SU Supersede 



outf ile/CD=inf ilel [, inf ile 2. ,.,infilen] 

outf ile=inf il el/CD [, inf ile 2. . . , inf ilen] 

Gives the output file the creation date of the input file rather 
than the date of transfer. This switch cannot be used with the 
Merge switch (/ME) and/or with an output magnetic tape device. 



,/DD:startdate :enddate 

Restricts file searches to files created during a specified 
period of time. 



infilel[,infile2...,infilen] /DE [/LD] 

Deletes files from a UFD. (/LD is the List Deleted files 

subswitch.) See the sections on Delete (3.2.2.5) and Purge 

(3.2.2.17) for a complete description of the List Deleted files 
subswitch. 



ddnn: [ufd] /DF or ddnn:/DF or [ufd]/DF or /DF 

Changes the default device and/or UFD for the current PIP task. 



outf ile= inf ilel [, inf ile 2. . . , inf ilen] /EN [/NV] 

Enters a synonym for a file in a directory or directories on the 
same device with an option to force the version number of outfile 
to one greater than the latest version for the file. (/NV is the 
New Version subswitch.) 



infilel/EOF [: block :byte] [. . . , inf ilen/EOF [: block :byte] ] 
Specifies the end-of-file pointers for a file. 



f ilespec/EX 



Excludes all the files specified with the file specification 
during a file search. 
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outf ile=/FI: f i lenum tseqnum 

Accesses an existing file by its file identification number. 



[ddnn: ]/FR 

Displays the amount of available space on a specified volume, the 
largest contiguous space on that volume, the number of available 
headers, and the number of headers used. If ddnn: is not 
specified, it defaults to SYO:. 



/ID 

Identifies the version of PIP being used and if PIP is linked to 
ANSFCS. 



[listfile=]infilel[...,infilen]/LI [sub switch] 

Lists one or more files contained in a UFD with an option to 

specify directory listing formats ([listfile] defaults to TI: if 

not specified). In place of /LI, you can specify one of the 
alternate mode subswitches: 

/BR Brief format 

/FU[:n[.]] Full format 

/TB Total blocks format 



infilel[,infile2. .., inf ilen] /sw/NM 

Deletes certain PIP error messages, for example, NO SUCH FILE(S). 
/sw can be /LI (List directory) , /DE (Delete files) , or /PU 
(Purge files) , or any of their respective subswitches, or /UN 
(Unlock files) . 



infile/PR[/SY[:RWED]] [/0W[ : RWED] ] [/GR [ : RWED] ] [/WO[:RWED]] [/FO] 

Sets the protection status for a file. The switches are: 

/SY — system access rights 
/OW — owner access rights 
/GR — group access rights 
/WO — world access rights 
/FO — File Owner subswitch 

The privileges are: 

R — Read 
W — Write 
E — Extend 
D — Delete 

You can specify any of the letters in any order. 



inf ilel [,inf ile2. . . , inf ilen] /PU [:n] [/LD] 

Deletes a specified range of obsolete versions of a file. (The 
switch never deletes the latest version of a file.) (/LD is the 
List Deleted files subswitch.) 
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outf ile=inf ilel [,inf ile2. . . ,inf ilen] /RE [/NV] 

Changes the name of a file with an option to force the version 
number of outfile to be one greater than the latest version for 
the file. (/NV is the New Version subswitch.) 

infilel[,infile2...,infilen] /RM 

Removes an entry from a UFD, but does not delete the file 
associated with that entry. 



outf ile/RW=inf ile or outf ile=inf ile/RW 

Rewinds a magnetic tape. When you specify /RW with the output 
file specification, PIP begins writing the file at the beginning 
of the tape. When you specify /RW with the input file 
specification, PIP rewinds the tape before searching for the 
input file. 



outdsk :outf ile/SB=inmag :inf ile 

The file copied to disk from magnetic tape may have records 
crossing block boundaries. (/SB is the default.) If you specify 
/-SB, the records will not cross block boundaries. 



infilel[,infile2...,infilen] /SD 

Prompts for user response before deleting files. 



infilel[,infile2...,infilen] /SP[:n] 

Specifies a list of files to be printed on a line printer (n is 
the number of copies) . 



outf ile=inf ile/SR 

Allows shared reading of a file that has already been opened for 
writing . 



Restricts file searches to files created on the current day. 



infilel[,infile2...,infilen] /TR 

Truncates files to their logical end-of-file point. 



outf ile/UF [/FO]=infilel [,inf ile 2. . . ,inf ilen] 

Creates a User File Directory entry in the Master File Directory 
of the volume specified with outfile. 



A-8 



COMMANDS AND SWITCHES 



inf ilel [,inf ile2. . . , inf ilen]/UN 

Unlocks a file that was locked as a result of being improperly 
closed . 

outf ile= inf ilel [ , inf ile2. . . , inf ilen] /UP [/FO] 

Opens an existing file (outfile) and writes new data (infile) 
into it from the beginning. (/FO is the File Owner subswitch.) 

A. 4 FLX COMMAND SUMMARY 

The FLX commands generally have the form: 

outspec/sw= inf ilel [ , inf ile2. . . , inf ilen] /switch 
/switch can be one or more of the following: 
/BL: n [ . ] 

Specifies the number of contiguous blocks (n) in octal or decimal 
to be allocated to the output file. 

/BS:n 

Specifies the block size (n) for cassette tape output. 

/CO 

Specifies that the output file is to be contiguous. 

/DE 

Deletes files from a DOS-11 or RT-11 (used with the /RT switch) 
volume. 

/DI 

Causes a directory listing of a cassette or DOS-11 volume or, 
when used with the /RT switch, of an RT-11 volume. The directory 
is placed in the specified output file. 

/DNS :n 

Specifies a density of 800, 1600, or 6250 bpi for a magnetic tape 
volume. 

/DO 

Identifies the volume as a DOS-11 formatted volume. 

/FA:n 

Specifies formatted ASCII transfer mode file format. 

/FB:n 

Specifies formatted binary transfer mode file format. 
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/FC 

Specifies that FORTRAN carriage control conventions are to be 
used . 

/ID 

Displays the current version number of FLX. 

/IM:n 

Specifies image mode (n is in decimal bytes) . 

/LI 

Same as /DI. 
/NU:n[. ] 

Used with /ZE and /RT switches; specifies the number of 
directory blocks (n) in octal or decimal to allocate when 
initializing an RT-11 disk or DECtape. 

/RS 

Identifies the volume as a Files-11 formatted volume. 

/RT 

Identifies the volume as an RT-11 formatted volume. 
/RW and /-RW 

Specifies whether the magnetic tape will rewind before FLX begins 
the file transfer. 

/SP 

Specifies that the converted file is to be spooled by the print 
spooler or the Queue Manager. 

/UI 

Specifies that the output file is to have the same UFD as the 
input file. 

/VE 

Verifies each record written to a cassette. 
/ZE[:n. ] 

Initializes cassettes or DOS-11 volumes or, when used with the 
/RT switch, RT-11 volumes. Initializing erases any files already 
on the volume. 
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A. 5 FMT COMMAND SUMMARY 

The general format of an FMT command line is: 

FMT ddnn : [/switchl. . ./swi tchn] 
/switch can be one or more of the following: 
/BAD 

Runs the Bad BLock Locator Utility if it is installed. Note that 
this switch can only be used with operating systems that allow 
spawning of tasks. RSX-11M provides spawned tasks as a system 
generation option. RSX-11M-PLUS always includes support for 
spawned tasks. 

/DENSITY or /DENS 

Selects high (double) or low (single) density for RX02 floppy 
diskettes. 

/ERL 

Determines the maximum number of errors FMT will allow on the 
volume . 

/MANUAL or /MAN 

Enters manual operating mode and formats the sector or track you 
specify. 

/NOVERIFY or /NOVE or /-VERIFY or /-VE 

Inhibits the default verification of a successful FMT operation. 

/OVR 

Overrides or ignores the manufacturer's bad block sector file 
(MDBSF) . 

/VERIFY or /VE 

Verifies that an FMT operation was successfully completed. This 
switch is the default. 

/WLT 

Rewrites the MDBSF (on the last track of the device) to add bad 
sectors found during an FMT operation. 

/@Y 

Informs FMT that it is receiving input from an indirect command 
file. User intervention is not allowed during the operation. 
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A. 6 BAD COMMAND SUMMARY 

The format for executing BAD is: 

ddnn: [/swl. . ./swn] 

/sw can be one or more of the following: 

/ALO:volume label 

Prompts you for blocks to be allocated to BADBLK. SYS and to be 
entered in the bad block descriptor file. 

/CSR=nnnnnn 

Specifies the CSR address of a device that is not in a standard 
location (stand-alone version of BAD only) . 

/LI 

Lists bad blocks as they are located. 

/MAN 

Allows you to enter bad blocks, which are then included in the 
bad block descriptor file. 

/NOWCHK 

Negates the effect of /WCHK (see below). 

/OVR 

Creates the bad block descriptor file on a last-track device. 
/PAT=m:n 

Specifies the double-word data pattern used to locate bad blocks. 
/RETRY 

Recovers soft errors. 

/UPD 

Reads the bad block descriptor file and prompts for user entries. 
/VEC=nnn 

Specifies the interrupt vector address of a device that is not in 
a standard location (stand-alone version of BAD only) . 

/WCHK 

Causes a write-check operation to take place after each write 
operation (stand-alone version of BAD only) . The switch is not 
valid for DT : DX:-, or DY:-type devices. 
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A. 7 BRU COMMAND SUMMARY 

The format for executing BRU is: 

[/qual if iers] indevl : , . . . [ f ilespec , . . . ] outdevl : , . . . [ f ilespec , . . . ] 
/qualifiers can be one or more of the following: 
/APPEND 

Appends new backup data to a tape with one or more backup sets. 

BACKU P_SET :name 

Specifies the name of the backup set to be placed on tape. 

/BAD f '.MANUAL 

: AUTOMATIC 
_: OVERRIDE 

Enters the locations of bad blocks on volumes. The default is 
/BAD: AUTOMATIC. 

/BUFFERS: number 

Specifies the default number of directory File Control Blocks 
(FCBs) per volume kept by the ACP. 

/COMPARE 

Compares the data on the output volume to the data on the input 
volume and reports any differences. 

/CREATED:/ BEFORE :dd-mmm-yy 
1 BEFORE :hh :mm : ss 
) BEFORE (dd-mmm-yy hh:mm:ss) 
\ AFTER :dd-mmm-yy 
/ AFTER :hh :mm:ss 
\AFTER: (dd-mmm-yy hh:mm:ss) 

Directs BRU to process files created before or after a specified 
date and/or time. 

/DENSITY:number 

Specifies the data density at which BRU writes to tape. The 
default is /DENSITY: 6250. 

/DIRECTORY 

Displays information (such as backup set names, file names, or 
volume number of a tape) for a specified tape volume. 

/DISPLAY 

Displays at your terminal the UFD and file name of each file 
being backed up. 

/ERRORS :number 

Specifies the number of nonfatal I/O errors BRU tolerates on tape 
reads during a restore operation before automatically terminating 
execution. The default is 25(10) errors. 
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/EXCLUDE 

Excludes selectively from a back-up or restore operation all 
files specified on the command line. 

/EXTEND:number 

Specifies the number of blocks by which a file is extended when 
that file has exhausted its allocated space. 

/HEADERS rnumber 

Specifies the number of file headers to allocate initially to the 
index file. 

/INITIALIZE 

Directs BRU to initialize the output disk before proceeding with 
the operation. 

/INVOLUME:name 

Specifies the volume label of the input disk. 

/LENGTHrnumber 

Specifies the length of the output tape in decimal feet. 
/MAXIMUM: number 

Specifies the maximum number of files that can be placed on a 
volume as determined by the number of file headers in the 
volume's index file. 

/MOUNTED 

Allows you to back up files from a disk that is mounted (with the 
MCR or DC L MOUNT commands) as a Files-11 volume. 

/NEW_VERSION 

Directs BRU to resolve conflicts resulting from files with 
identical file specifications by creating a new version of the 
file. 

/NOINITIALIZE 

Specifies that you do not want to initialize the output disk 
because it is already in Files-11 format. 

/NOPRESERVE 

Specifies that you do not want to preserve file identifiers. 
/NOSUPERSEDE 

Resolves the conflict of files on the output volume having file 
specifications identical to files on the input volume by not 
transferring the file on the input volume. Therefore, the file 
on the output volume is not superseded. (The default is 
/NOSUPERSEDE. ) 
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/OUTVOLUMErname 

Specifies the volume label of the output disk. The label can be 
up to 12(10) characters long. 

/position: (beginning 
Imiddle 

j END 

IBLOCK:number 

Specifies the location of the index file on the output disk 
volume . 

/PROTECTION: (SYSTEM :value 
) OWNER: value 
)GROUP:value 
(WORLD: value 

Specifies the default protection status for all files created on 
the output volume being initialized. 

/REVISED:/BEFORE :dd-mmm-yy 
I BEFORE :hh :mm:ss 
J BEFORE : (dd-mmm-yy hh:mm:ss) 
\ AFTER :dd-mmm-yy 
/ AFTER: hh :mm : ss 
\ AFTER: (dd-mmm-yy hh:mm:ss) 

Directs BRU to process files revised before or after a specified 
date and/or time. 

/REWIND 

Rewinds the first tape of a tape set before performing the 
operation . 

/SUPERSEDE 

Resolves file specification conflicts by deleting the old file on 
the output volume and replacing it with the file from the input 
volume. (The default is /NOS UPERSEDE . ) 

/TAPE_LAB EL: label 

Specifies a 6-character ANSI volume identifier for identifying 
the tape volume. 

/UFD 

Directs BRU to create UFDs (if they do not already exist) on a 
mounted output volume, then copy into them the files from the 
same UFDs on the input volume. 

/VERIFY 

Copies data from the input volume to the output volume, compares 
the volumes, and reports any differences. 

/WINDOWS :number 

Specifies for the output disk the default number of mapping 
pointers allocated for file windows. The default number is the 
same as for the input disk. 
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A. 8 DSC COMMAND SUMMARY 

The format for executing DSC is: 

outdev[s] : [label] [/switch] =indev [s] : [label] [/switch] 
/switch can be one or more of the following: 
/AP 

Appends a DSC file to the first volume of a magnetic tape set 
that already contains a DSC file. 

I MAN \ 
NOAUTO / 
MAN:NOAUTOj> 
OVR I 
MAN: OVR ) 

Allows manual entry of bad block locations; can supplement, 
override, or ignore the disk's own bad block file. 



/BL=n or /BL:n 



Sets the number of 256-word blocks DSC can include in each of its 
two buffers. 



/CMP 



Compares input and output volumes for differences. 



/CSR=xxxx 

Specifies control status addresses for a specific Status Control 
Block (SCB) . /CSR is valid only with the stand-alone version of 
DSC. 



/DENS=1600 or /DENS: 1600 
/DENS=800: 1600 or /DENS : 80 : 1 60 
/DENS=6250 



/RW 



Overrides the DSC default storage density for magnetic tapes of 
800 bpi . The first form of the switch creates magnetic tapes at 
1600 bpi density. The second form (the split density switch) 
creates magnetic tapes with volume header information at 800 bpi 
and the rest of the tape at 1600 bpi. The third form creates 
magnetic tapes at 6250 bpi. The /DENS=6250 option is valid with 
TU78 tapes only. 



Rewinds all volumes in a magnetic tape set before execution of 
the current command line. 



/TM02=x 



Specifies the physical unit number of the formatter on the 
RH11/RH70 controller (stand-alone version of DSC only) . 



/UNIT=x 

Specifies the physical unit that will be referenced by the 
indicated Unit Control Block (UCB) . The /UNIT switch is valid 
only with the stand-alone version of DSC. 
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/VE 

Copies data from the input volume and compares it with the output 
volume following the data transfer. 

/VEC=xxx 

Specifies the vector address for a specific Status Control Block 
(SCB) . The /VEC switch is valid only with the stand-alone 
version of DSC. 



A. 9 VFY COMMAND SUMMARY 

1 istf ile,scratchdev=indev/DE 
or 

ind ev/DE 

Resets the marked-for-delete indicators in the file header area 
of those files marked for deletion but never actually deleted. 



listf i 1 e, sera tend ev=indev/DV 
or 

indev/DV 

Validates directories against the files they list. 

listf ile=indev/FR 
or 

indev/FR 

Displays the amount of available space on a volume. 



listf ile ,sc rate hd ev=indev/HD 
or 

ind ev/HD 

Recognizes all bad file headers on a volume. The /AL subswitch 
allows all bad headers to be automatically deleted with no user 
intervention . 



listfile f scratchd ev=indev/LI 
or 

ind ev/LI 

Lists the index file by file identification. 



1 i stf ile, sc rate hdev=indev/LO 
or 

indev/LO 

Scans the file structure looking for files that are not in any 
directory and cannot be referenced by file name. 
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listf ile=indev/RC [:n] 
or 

indev/RC [ :n] 

Ensures that every block of every file on the specified volume 
can be read. The optional parameter [:n] indicates how many 
blocks are to be read at a time. 



li stf ile r scratchdev=indev/RE 
or 

indev/RE 

Recovers blocks that appear to be allocated but are not contained 
in any file. 



listf ile / scratchdev=indev/UP 
o r 

indev/UP 

Allocates blocks that appear to be available but are actually 
allocated to a file. 



A. 10 LBR COMMAND SUMMARY 

outf ile/CO: si ze:ept:mnt:=infile 

Compresses a library file by physically deleting logically 
deleted records, putting the free space at the end of the file, 
and making the free space available for new library module 
inserts . 



outf ile/CR:si ze :ept :mnt :1 ibtype=inf iletype 

Allocates a contiguous library file on a direct access device 
(for example, a disk). 



outf ile/DE rmodulel [: module 2. . . :modulen] 

Logically deletes library modules and their associated entry 
points from a file. 



outf ile/DF : type . . . 
or 

/DF: type 

Specifies the default library file type. 



outf ile/DG: global 1 [:global2: rglobaln] 

Deletes the specified library module entry points from the entry 
point table. 
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outf ile[/EP]=inf ile[ . . . , inf ilen] 
or 

outf ile= inf ile[/EP] [. . . , inf ilen [/EP] ] 

Includes or excludes entries in the entry point table. 



outf ile=inf ile/EX[ rmodulenamel: . . . :modulenamen] 

Reads (extracts) one or more modules from a library and writes 
them into the specified output file. 



outf ile/IN=in file 1 [,infile2...,infilen] 
or 

outf ile= inf ile/IN: name :op:op:op:op (universal) 
Inserts library modules into a library file. 



outfile[,listfile] /switch(es) 

Lists all modules in the library file plus additional 
information, depending on which form of the switch you use: 

/LI Lists all modules in the library file. 

/LE Lists all modules in the library file and their 

corresponding entry points. 

/FU Lists all modules in the library file and provides a 

full module description that includes the size, date of 
insertion, and module-dependent information. 



outf ile/MH: module :op:op:op:op 

Modifies the optional user-specified information in the module 
header of a universal library. 



outf ile/RP=inf ilel [, inf ile2. .., inf ilen] (global format) 
or 

outf ile=inf ilel/RP[,inf ile2[/RP] . . . , inf ilen [ /RP] ] (local format) 
or 

outf ile/RP: name :op:op:op:op=infilel[,infile2..., inf ilen] (universal/global format) 
or 

out file= inf ilel/RP: name :op:op:op:op[,infile2...,infilen] (universal /local format) 

Replaces or, in certain cases, inserts library modules in a 
library file. 



outf ile, list file/SP 

Spools the listing file for printing. This is the default 
setting; use /-SP to prevent the file from being printed. 



outf ile=inf ilel/SS [,inf ile2[/SS] . . . , inf ilen [/SS] ] 

Sets the selective search attribute bit in the object module 
header . 
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outf ile/SZ=inf ilel [,inf ile2. . . ,inf ilen] (global format) 
or 

outf ile=inf ilel/SZ [ , inf ile2 [/SZ ] . . . , inf ilen[/SZ ] ] (local format) 

Reduces the size of macro definitions by removing comments, blank 
lines, and trailing blanks and tabs from the macro text. 



A. 11 DMP COMMAND SUMMARY 

The format for executing DMP is: 

[outfile] [/swi tch (es) ] [=inspec] [/swi tch (es) ] 
/switch can be one of the following: 
/AS 

Specifies that data be dumped one byte at a time in ASCII mode. 
/BA:n :m 

Specifies a two-word base block address. 
/BL:n :m 

Specifies the first and last logical blocks to be dumped. 

/BY 

Specifies that data be dumped in octal byte format. 

/DC 

Specifies that data be dumped in decimal word format. 
/DENS :n 

Specifies density of an input magnetic tape when DMP is in device 
mode only. Values for n can be 800, 1600, or 6250. 

/FI: file-number :sequence-number 

Specifies the input file with its file-ID instead of its name 
(File Mode only) . 

/HD[:F or :U] 

Includes the file header in the data dumped. "F" , the default, 
specifies a formatted Files-11 dump for the header. "U" 

specifies an unformatted octal dump. 

/HF 

Specifies the format for data blocks that have the Files-11 

header structure. Other blocks are dumped as unformatted octal. 

/HX 

Specifies that data be dumped in hexadecimal byte format. 
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/ID 

Causes the current version of DMP to be displayed or printed. 

/LB 

Requests the starting (logical) block number and a contiguous or 
noncontiguous indication for the file to be displayed. 

/LC 

Specifies that the data should be dumped in lowercase characters. 
This switch is valid only if the output device supports lowercase 
characters . 

/LW 

Specifies that data be dumped in hexadecimal double-word format. 
/MD[:n] 

Controls line number sequencing during a memory image dump. 

/OCT 

Specifies that the data should be dumped in octal format. If no 
DMP format switches are included, the default is octal format. 

/RC 

Dumps one record at a time in the specified format. 

/RW 

Issues a rewind command to the tape driver before referencing a 
specified tape. The /RW switch can be used at any time to 
reposition a tape at beg inning-of-tape (BOT). 

/R5 

Dumps in Radix-50 word format. 
/SB:n or /SB:-n 

Specifies the number of blocks DMP spaces forward (n) or 
backwards (-n) on a tape. 

/SF:n or /SF:-n 

Specifies the number of end-of-file (EOF) marks DMP spaces 
forward (n) or backward (-n) on a tape. 

/SP 

Spools the dump file (the output file) to the line printer. 

/WD 

Specifies that data be dumped in hexadecimal word format. 
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A. 12 CMP COMMAND SUMMARY 

The CMP command line takes the following form: 

[outf ile [/sw. . ,]=]infilel,infile2 
/sw can be any one of the following: 
/BL or /-BL 

Specifies that blank lines in both files be included in compare 
processing. If specified in the form /-BL, blank lines are not 
included in compare processing. /-BL is the default switch. 

/CB or /-CB 

Specifies that CMP list infile2 with change bars, in the form of 
exclamation marks (!), to denote each line that does not have a 
corresponding line in infilel. /-CB is the default switch. 

You can change the change bar character from the exclamation mark 
to any character you wish by means of the /VB switch, described 
below. 

When a section of lines in infilel has been deleted in infile2 
(the output listing file), the first line after the deleted lines 
is marked. 

/CO or /-CO 

Specifies that CMP include comments (that is, text preceded by a 
semicolon) in compare processing. /CO is the default switch. 

/DI or /-DI 

Specifies that CMP list the differences between the two files 
(rather than marking the lines in inf ile2) . /DI is the default 
swi tch . 

/CB and /DI are mutually exclusive switches. If both are 
specified, /CB overrides /DI. 

/FF or /-FF 

Specifies that CMP include records consisting of a single 
form-feed character in compare processing. /-FF is the default 
swi tch . 

/LI:n 

Specifies that a number (n) of lines must be identical before CMP 
recognizes a match. If you do not specify this switch, CMP 
searches for three identical lines to match (/LI: 3). 

When it encounters a match, CMP prints all the preceding 
nonmatching lines, along with the first line of the matched 
sequence of lines to help you find the location in the code where 
the match occurred. 
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/LN or /-LN 

Specifies that lines in the output file be preceded by their line 
number. Line numbers are incremented by one for each record 
read, including blank lines. /LN is the default switch. If you 
specify /SL (below) , /LN is unnecessary. 

/MB or /-MB 

Specifies that CMP include all blank and tab characters in a line 
in compare processing. If you specify /-MB, CMP interprets any 
sequence of blank and/or tab characters as a single blank 
character in compare processing. However, all spaces and tabs 
are printed in the output listing. /MB is the default switch. 

/SL[:au] 

Directs CMP to generate an output file suitable for use as SLP 
command input. When you specify /SL, CMP generates the SLP 
command input necessary to make infilel identical to infile2. If 
a 1- to 8-character alphanumeric symbol is included (:au), an 
audit trail is specified for SLP input. 

/SP[:n] or /-SP 

Specifies that the output file be spooled on the line printer. 
You can optionally specify the number (in octal or decimal) of 
files to be spooled. /-SP is the default switch. 

This switch applies only if you have the print spooler task 
(RSX-11M) or the Queue Manager (RSX-1 1M/M-PLUS ) installed. 

/TB or /-TB 

Specifies that CMP include all trailing blanks on a line in 
compare processing. If you specify /-TB, CMP ignores all blanks 
following the last nonblank character on a line. When you 
specify /-CO and /-TB together, blanks that precede a semicolon 
(;) are considered trailing blanks and are ignored. /TB is the 
default switch. 

/VB:nnn 

Specifies an octal character code for use as a change bar. You 
use this switch with the /CB switch. The value nnn specifies the 
octal character code. For example, you can specify /VB:174 for a 
vertical bar (if your printer is capable of printing the vertical 
bar character). /VB:041 (for the exclamation mark) is the 
default switch. 



A. 13 SLP COMMAND SUMMARY 

The format of a SLP command line is: 

outf ile[ /switch, 1 istf ile/[-]SP] =infile[ /switch] 
/switch can be any one of the following: 
/AU or /-AU 

Enables or disables the audit trail, which indicates the changes 
made during the most recent editing session. 
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/BF or /-BF 

Enables or disables blank fill (right- justification) for an audit 
trail . 

/CM[:n] 

Deletes the audit trail and any trailing spaces or tabs, and 
truncates the text at the specified horizontal position. 

/CS[:n] 

Calculates the checksum value for the edit commands. 
/DB or /-DB 

Enables or disables double-spaced listings. /-DB is the default 
swi tch . 

/NS 

Does not sequence lines in the output file. New lines are 
indicated by the audit trail (if specified). This switch 
overrides the /RS and /SQ switches. 

/RS 

Resequences the lines in the output file so that the line numbers 
are incremented for each line written to the output file. 

/SP or /-SP 

Enables or disables the spooling of listing files to a line 
printer. This switch applies only if the print spooler task 
(RSX-11M) or the Queue Manager (RSX-1 1M/M-PLUS ) is installed. 

/SQ 

Sequences the lines in the output file so that the numbers 
reflect the line numbers of the original input file. 

/TR 

Specifies that a diagnostic error message occur when lines are 
truncated by the audit trail. 

A. 14 PAT COMMAND SUMMARY 

The format for specifying execution of PAT is: 

[outf ile] =infile[/CS [: number] ] , correctf ile[/CS [: number] ] 

The /CS switch provides the facility to calculate the checksum for all 
the binary data of a specified module. 
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A. 15 ZAP COMMAND AND SWITCH SUMMARY 

The ZAP command line is in the form: 

ddnn: [ufd] f ilename . f iletype ; version [ /sw. . . ] 

A. 15.1 ZAP Open/Close Commands 

/ (slash) 

Opens a location, displays its contents in octal, and stores the 
contents of the location in the Quantity Register (Q) . If the 
location is odd, it is opened as a byte. 

" (quotation mark) 

Opens a location, displays the contents of the location as two 
ASCII characters, and stores the contents of the location in the 
Quantity Register (Q). 

% (percent sign) 

Opens a location, displays the contents of the location in 

Radix-50 format, and stores the contents of the location in the 

Quantity Register (Q). 

\ (backslash) 

Opens a location as a byte, displays the contents of the location 
in octal, and stores the contents of the location in the Quantity 
Register (Q). 

' (apostrophe) 

Opens a location, displays the contents as one ASCII character, 
and stores the contents of the location in the Quantity Register 
(Q) . 

© (RETURN key) 

Closes the current location as modified and opens the next 
sequential location if no other values or commands are on the 
command line. ZAP commands take effect only after you press the 
RETURN key. 

or + (circumflex or up arrow) 

Closes the currently open location as modified and opens the 
preceding location. 
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_ (underscore) 

Closes the currently open location as modified, uses the contents 
of the location, as an offset from the current location, and 
opens the new location. 

@ (at sign) 

Closes the currently open location as modified, uses the contents 
of the location as an absolute address, and opens that location. 

> (right angle bracket) 

Closes the currently open location as modified, interprets the 
low-order byte of the contents of the location as the relative 
branch offset, and opens the target location of the branch. 

< (left angle bracket) 

Closes the currently open location as modified, returns to the 
location from which the last series of underscore (_) , at sign 
(@) , and/or right angle bracket (>) commands began, and opens the 
next sequential location. 



A. 15. 2 ZAP General-Purpose Commands 
X 

Exits from ZAP, returns control to the CLI. 

K 

Calculates the offset in bytes between an address and the value 
contained in a Relocation Register, displays the offset value, 
and stores it in the Quantity Register (Q). 



Displays the jump and branch displacements from the current 
location to a target location. 



Displays in octal the value of the expression to the left of the 
equal sign. 

V 

Verifies the contents of the current location. 

R 

Sets the value of a Relocation Register. 
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A. 15. 3 ZAP Switches 
/AB 

Specifies absolute mode. 

/LI 

Displays the overlay segment table for an overlaid task image 
file. 

/RO 

Specifies read-only mode. 
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THE CROSS-REFERENCE PROCESSOR (CRF) 



The Cross-Ref erence Processor (CRF) is an independent task that 
produces cross-reference listings for the MACRO-11 and Task Builder 
tasks. CRF is invoked by the /CR switch in the MACRO-11 or Task 
Builder command line. Once execution is complete, CRF builds 
cross-reference listings using the execution-time symbol tables built 
by those tasks. 

Two cross-reference listings are built for the Task Builder, one 
listing the modules that reference global symbols during task 
execution and another that shows the modules contained in a given 
overlay segment. 

Four cross-reference listings are produced for the MACRO-11 task, each 
showing a page and line number reference to a type of symbol 
referenced during execution of the MACRO-11 Assembler. 

This appendix describes how CRF processes data and shows the formats 
of files CRF uses during that processing. Also, CRF error messages 
are listed. 

For information on how to invoke CRF in the MACRO-11 command line, 
refer to the PDP-11 MACRO-11 Language Reference Manual. For 
information on how to invoke CRF with the Task Builder command line, 
refer to the RSX-11M/M-PLUS Task Builder Manual . 



B.l HOW CRF PROCESSES DATA 

When the /CR switch is specified in the MACRO-11 or Task Builder 
command line, those tasks perform additional processing before passing 
control to the CRF processor. This section describes how 
cross-reference listings are generated in two phases. The first phase 
consists of the processing steps performed by MACRO-11 or Task 
Builder; the second phase consists of processing steps performed by 
CRF. Figure B-l is an overview showing the processing steps performed 
in each phase, along with input and output files used. 



B.l.l MACRO-11 or Task Builder Processing 

The first steps to produce cross-reference listings are performed by 

the MACRO-11 Assembler or the Task Builder and the /CR switch. These 

tasks generate three files during execution: an object file 

(filename. OBJ) or task image file ( f i lename . TSK) , a listing file 

(filename. LST or f ilename.MAP) , and a CRF symbol table file 
(filename. CRF) . 
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The object file or task image file is directed to an appropriate 
device and does not affect CRF processing. 



INPUT PROCESS OUTPUT 
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Figure B-l How MACRO-11, the Task Builder, and CRF Generate 

Cross-Ref erence Listings 



The listing file consists of text information generated during the 
execution of the tasks, for example, the listing of the source code in 
a MACRO-11 program. If the output device for the listing file is 
sequential or record-oriented, as in the case of LP:, a temporary 
listing file is created on SYO:. 

The CRF symbol table file consists of symbol tables built during 
MACRO-11 or Task Builder execution. These tables are used by CRF to 
generate cross-reference listings. 

The task originating the request for cross-reference processing then 
sends CRF a SEND packet, using information in the listing file and the 
file name and file type specified on the command line. The SEND 
packet contains enough data to identify the symbol table file and the 
listing file. CRF receives the packet and uses it to locate the 
symbol table file and listing file produced by MACRO-11 or the Task 
Bui lder . 

The formats of the symbol table file and the SEND packet are shown in 
Figures B-2 and B-3. 

If spooling is requested with the /SP switch and the output device is 
a random-access device, the spooling flag in the SEND packet is set. 
CRF then passes the listing file to the print spooler for printing. 
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B.1.2 CRF Processing 

The SEND packet contains pointers to the CRF symbol table file and the 
listing file. CRF uses the information in the listing file and the 
SEND packet to specify the symbol table file for processing 
(filename. CRF) : 

Symbol table filename - Text file name 

Symbol table filetype - CRF 

Symbol table version - Contents of SEND packet word 11 
Symbol table 

device and unit - Listing file device and unit 

CRF then generates the requested cross-references and appends them to 
the listing file. When all cross-references have been generated, CRF 
deletes filename. CRF. 



B.2 THE CRF SYMBOL TABLE FILE 

The CRF symbol table file is a series of contiguous 5-word data 
records preceded by a 9-word header record, as shown in Figure B-2. 
The symbol table file is assumed to reside on the same device and have 
the same name as the input listing file, except that the file has a 
filetype of CRF, that is: 

filename. CRF 

The header record contains the name of the originating task in 2-word 
Radix-50 format, followed by a number value assigned by the system to 
identify the task. This value allows CRF to locate the internal 
tables CRF uses to format output. The next five words define the 
creation date of the symbol table file. The last word contains the 
flags that define the output format. 

Bit zero of the flags word controls the width of the listing. When 
this bit is set to zero, the listing is generated in 132-column 
format. When this bit is set to one, the listing is generated in 
80-column format. 

The remaining records in the symbol table file are data records. The 
first two words of a data record comprise the symbol name in Radix-50 
format. The symbol value is an octal quantity associated with the 
symbol name. The second two words comprise the reference identifier, 
which is used as the cross-reference value. In the case of global 
symbols, this value is the module name in Radix-50 format. In the 
case of MACRO-11 cross-references, the value is the page and line 
number of the reference. The last word of the data record comprises 
the attribute flag byte and the format number byte. 

The attribute flag byte contains the bits describing the attributes of 
the reference. These flags cause the special characters and 
abbreviations to be displayed with the reference. A pound sign (#) 
means that the reference is the place where the symbol is defined. An 
asterisk (*) means that there is a destructive reference to the symbol 
(that is, its contents are changed). If there is nothing in front of 
the reference, it means that there is a nondestructive reference to 
the symbol (that is, its contents are read). 

The format number byte defines the format of the output. The format 
number is used by CRF to locate a set of internal tables that define 
the listing format associated with the entry. The type of 
cross-reference and the set of symbols associated with the flags byte 
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is determined by the format number. Use of the format byte permits 
several types of cross-reference output to be generated by a single 
originating task. 



CRF 
Symbol 
Table 
File 



Header 
Record 



Data Record 1 



Data Record 2 



Data Record n 



i 

i. 
3 

4 

3- 
1 
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Header Record 



Name of Originating Task 



Name of Originating Task (Cont.) 



Originating Task Identifier 



Year 



Month 



Day 



Hour 



Minute 



Flag Byte 



Data Record 



Symbol Name 



Symbol Name (Cont.) 



Reference Identifier 



Reference Identifier (Cont.) 



Format Number 



Attributes 



Data 
Records 
to 
EOF 



Figure B-2 Format of the CRF Symbol Table File 



B . 3 THE CRF SEND PACKET 

The CRF SEND packet is a block of data that contains control 
information created by the Task Builder or MACRO-11 for use by CRF. 
This control information enables CRF to locate the symbol table file 
and the listing or memory allocation output file. 

The SEND packet consists of 17 words, as described in Figure B-3. 

Words and 1 of the SEND packet contain the name of the sending task. 
Words 2 through 4 contain the file name of the output listing file in 
Radix-50 format. Word 5 contains the file type of the output listing 
file. Word 6 contains the version number of the output listing file. 
Words 7 through 11 contain the directory identifier. Word 12 contains 
the device name of the device on which the output listing file 
resides. The first byte of word 13 is a flag byte used by CRF for 
output processing. When this bit is set to 1, the output listing file 
is spooled off line when CRF completes processing. The second byte of 



B-4 



THE CROSS-REFERENCE PROCESSOR (CRF) 



word 13 specifies the unit on which the listing output file resides. 
Word 14 contains the symbol table file version number. Word 15 
contains the device name of the output device. The first byte of word 
16 is reserved. The second byte of word 16 is the unit number of the 
output device. 




1 
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10 
11 
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14 
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Fig 



Originating Task Name 



Originating Task Name (Cont.) 



Text Filename 
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File Version 
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Target Device Name 



Reserved 
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Two 

RADIX-50 
Words 



Three 

RADIX-50 

Words 
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B.4 CRF ERROR MESSAGES 

The following error messages are output by CRF, 
preceded by one of the following prefixes: 



Each message is 



CRF — *DIAG* - name of originating task - message 
CRF — *FATAL* - name of originating task - message 



CRF INPUT FILE filename HAS ILLEGAL FORMAT 

Explanation: This error is caused by a software error in the 
originating task. The symbol table file submitted for CRF 
processing contains no data. 

User Action: Submit a Software Performance Report with the 
related console dialogue and any other pertinent information. 
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FAILED TO DELETE FILE filename 

Explanation: CRF was unable to delete the specified file for one 
of the following reasons: 

• CRF did not have deletion privileges for the UFD under which 
the file resides 

• The device was not wr i te-enabled or ready to perform I/O 

User Action: Initialize the device appropriately and ensure that 
the UFD has owner-delete privileges. 



FILE filename NOT FOUND 

Explanation: The file could not be located. The file was 
probably deleted before CRF could process it. 

User Action: Rerun the appropriate task to produce 
cross-reference output. Do not delete any files until CRF 
completes processing. 



ILLEGAL ERROR/SEVERITY CODE data 

Explanation: This error indicates a CRF malfunction; CRF has 
called its error message processor with an illegal parameter. 

User Action: Submit a Software Performance Report containing a 
copy of the message as printed. 



INPUT FROM UNKNOWN TASK 

Explanation: Cross-reference processing requested by the 
originating task is not supported by CRF. 

User Action: Delete the request for CRF processing and rerun the 
originating task. 



I/O ERROR ON FILE filename 

Explanation: An error has been encountered while CRF was reading 
or writing the specified file. A possible hardware problem is 
indicated, or the device may have insufficient space to 
accommodate the CRF output file. 

User Action: Isolate the problem and take corrective action. 
Rerun MACRO-11 or the Task Builder to produce the cross-reference 
output . 



INVALID OUTPUT FORMAT SPECIFIED 

Explanation: This error indicates an inconsistency in the data 
file submitted for CRF processing. 

User Action: Submit a Software Performance Report with the 
related console dialogue and any other pertinent information. 
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NO DYNAMIC STORAGE AVAILABLE 

Explanation: The CRF task requires more working storage than is 
available within the area of memory owned by the task. 

User Action: If possible, install CRF in a larger partition or 
with a larger increment. 

NO VIRTUAL MEMORY STORAGE AVAILABLE 

Explanation: The CRF work file storage requirements exceed 
65, 536 words. 

User Action: No recovery is possible from this error. If 
possible, install the task in a larger partition. 

OPEN FAILURE ON FILE filename 

Explanation: CRF was unable to open the named file for one of 
the following reasons: 

• The device was not ready to perform I/O. 

• The device was not wr i te-enabled . 

• A Files-11 device was not mounted. 

• CRF did not have extend or delete privileges for the UFD 
under which the file resides. 

• The file was deleted before it could be processed by CRF. 

User Action: Isolate the problem, take appropriate corrective 
action, and rerun the task to obtain cross-reference output. 

SYMBOL TABLE SEARCH STACK OVERFLOW 

Explanation: This error indicates a CRF malfunction. 

User Action: Submit a Software Performance Report with the 
related console dialogue and any other pertinent information. 

UNABLE TO OPEN WORKFILE 

Explanation: Possible causes are: 

• The workfile device is not mounted. 

• The workfile device is write protected. 

The workfile device is assigned to LUN 7 and is normally the 
device from which CRF was installed. 

User Action: Retry the command after ensuring that the device is 
mounted and write enabled. 



B-7 



THE CROSS-REFERENCE PROCESSOR (CRF) 



WORK FILE I/O ERROR 

Explanation: CRF encountered an I/O error while reading or 
writing data to its workfile. Possible causes are: 

• Device is full 

• Hardware error 

User Action: If the device capacity has been exceeded, delete 
unnecessary files to make space available. Also, REASSIGN CRF 
LUN7 to another Files-11 device. 



B-8 



INDEX 



/AB switch 

ZAP utility, 15-2 
ADD & PRINT command 

EDI utility, 2-12, 2-28 
ADD command 

EDI utility, 2-11, 2-27 
Address boundary 

See ZAP utility 
/ALLOCATE switch 

BAD utility, 6-5 
AP command 

EDI utility, 2-12, 2-28 
/AP switch 

PIP utility, 3-14 
/APPEND qualifier 

BRU utility, 7-12 
/APPEND switch 

DSC utility, 8-9 
/AS switch 

DMP utility, 11-3 
Asterisk 

See Wildcard 
/AU switch 

SLP utility, 13-15 
Audit trail 

See SLP utility 



/BA switch 

DMP utility, 11-3 
Backing up volume 
See BRU utility 
See DSC utility 
Backup and Restore Utility 

See BRU utility, 7-1 
/BACKUP_SET qualifier 

BRU utility, 7-13 
Bad block 
information 

DSC utility, 8-9 
locating 

BAD utility, 6-1 
FMT utility, 5-1 
VFY utility, 9-7 
processing 

BAD utility, 6-3 
BRU utility, 7-24 
Bad Block Locator Utility 

See BAD utility 
/BAD qualifier 

BRU utility, 7-13, 7-24 
options, 7-25 
/BAD switch 

DSC utility, 8-9 
FMT utility, 5-7 



BAD utility 

bad block descriptor entry, 
6-4 

bad block processing, 6-3 
command line, 6-1 
device support, 6-9 
device verifying, 6-3 
error message, 6-10 
indirect command file, 6-2 
INI command, 6-4 
programming consideration, 

6-5 
switch, 6-5 

stand-alone, 6-8 

summary, 6-1 

task, 6-5 
BEGIN command 

EDI utility, 2-28 
/BF switch 

SLP utility, 13-15 
/BL switch 

CMP utility, 12-2 
DMP utility, 11-4 
DSC utility, 8-12 
FLX utility, 4-6 
PIP utility, 3-11 
Block 

allocating 

VFY utility, 9-8 
recovering lost 

VFY utility, 9-7 
veri f ying 

VFY utility, 9-7 
BLOCK ON/OFF command 

EDI utility, 2-28 
Bottom command 

EDI utility, 2-12, 2-29 
/BR switch 

PIP utility, 3-25 
BRU utility 

bad block processing, 7-24 
command line, 7-5 

parameter, 7-6 
command qualifier 

description, 7-12 

function, 7-11 

summary, 7-8 
data transfer, 7-26 
device information, 7-1 
device support, 7-5 
disk initialization, 7-17 
error message, 7-34 
example, 7-28 
file creation date, 7-27 
file revision date, 7-27 
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BRU utility (Cont.) 
file treatment, 7-26 
file header, 7-27 
file synonyn, 7-27 
lost file, 7-27 
stand-alone, 7-22 
booting, 7-23 
CNF and, 7-22 
locating, 7-23 
system image copying, 7-26 
/BS switch 

FLX utility, 4-6 
PIP utility, 3-15 
/BUFFERS qualifier 

BRU utility, 7-14 
/BY switch 

DMP utility, 11-5 

/CB switch 

CMP utility, 12-2 
CC command 

EDI utility, 2-30 
CD command 

EDI utility, 2-30 
/CD switch 

PIP utility, 3-16 
CHANGE command 

EDI utility, 2-12, 2-29 
Checksum 

calculating 

SLP utility, 13-3 

file content validating 
PAT utility, 14-6 
CL command 

EDI utility, 2-29 
CLOSE & DELETE command 

EDI utility, 2-30 
CLOSE command 

EDI utility, 2-27, 2-29 
CLOSE SECONDARY command 

EDI utility, 2-30 
CLOSES command 

EDI utility, 2-30 
/CM switch 

SLP utility, 13-15 
/CMP switch 

DSC utility, 8-14 
CMP utility 

command line, 12-1 

error message, 12-6 

output file format, 12-4 

switch, 12-2 
default, 12-4 

CNF 

DSC64K . SYS and 

See DSC utility 
stand-alone BRU and 

See BRU utility 
/CO switch 

CMP utility, 12-2 
FLX utility, 4-6 
LBR utility, 10-10 
PIP utility, 3-11 



Command line 

format, 1-4 
/COMPARE qualifier 

BRU utility, 7-14 
CONCATENATION CHARACTER command 

EDI utility, 2-30 
/CR switch 

CRF utility, B-l 

LBR utility, 10-12 
/CREATED qualifier 

BRU utility, 7-14 
CRF utility 

data processing, B-l 

error message, B-5 

MACRO-ll/Task Builder, B-l 

SEND packet, B-4 

switch, B-l 

symbol table file, B-3 
Cross-Ref erence Processor 

See CRF utility 
/CS switch 

PAT utility, 14-6 

SLP utility, 13-15 
/CSR switch 

BAD utility, 6-8 

DSC utility, 8-21 



Data transfer 

BRU utility, 7-26 

DSC utility, 8-24 

FLX utility, 4-1 
/DB switch 

SLP utility, 13-15 
/DC switch 

DMP utility, 11-5 
/DD switch 

PIP utility, 3-16 
/DE switch 

FLX utility, 4-7 

LBR utility, 10-13 

PIP utility, 3-17 

VFY utility, 9-4 

DELETE & PRINT command 

EDI utility, 2-14, 2-31 
DELETE command 

EDI utility, 2-13, 2-31 
/DENS switch 

DMP utility, 11-5 

DSC utility, 8-14 
/DENSITY qualifier 

BRU utility, 7-14 
/DENSITY switch 

FMT utility, 5-8 
Device 

supported 



BAD util 



BRU utility, 7-5 



DSC util 



ty, 6-9 



ty, 8-4 



FLX utility, 4-2 

FMT utility, 5-5 
verifying 

BAD utility, 6-3 
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/DF switch 

LBR utility, 10-14 
PIP utility, 3-18 
/DG switch 

LBR utility, 10-15 
/DI switch 

CMP utility, 12-3 
FLX utility, 4-7 
Di rectory 
See UFD 
/DIRECTORY qualifier 

BRU utility, 7-15 
Disk 

backing up 

BRU utility, 7-1 

DSC utility, 8-1 
comparing 

DSC utility, 8-14 
compressing 

DSC utility, 8-3 
conventional backup 

BRU utility, 7-4 
copying 

BRU utility, 7-1 

DSC utility, 8-1 
data transfer 

DSC utility, 8-25 
displaying free space 

PIP utility, 3-23 

VFY utility, 9-5 
examining data 

DMP utility, 11-1 
formatting 

FLX utility, 4-4 

FMT utility, 5-1 
full backup 

BRU utility, 7-3 
image backup 

BRU utility, 7-4 
initializing 

BRU utility, 7-2, 7-17 
locating bad block 

BAD utility, 6-1 
mounting 

BRU utility, 7-2 
recovering 

lost block 

VFY utility, 9-7 

space 

DSC utility, 8-3 
restoring 

BRU utility, 7-1 
selective backup 

BRU utility, 7-3 
verifying, 9-1 

block 

VFY utility, 9-7 
Disk Save and Compress Utility 

Program 
See DSC utility 
Disk Volume Formatter Utility 
See FMT utility 



/DISPLAY qualifier 

BRU utility, 7-16 
DMP utility 

command line, 11-2 
error message, 11-12 
example, 11-8 
mode 

device, 11-2 
file, 11-1 
switch, 11-3 
/DNS switch 

FLX utility, 4-7 
/DO switch 

FLX utility, 4-4 
DOS-11 

device support 

FLX utility, 4-1 
file copying 

FLX utility, 4-3 
volume 
deleting 

FLX utility, 4-10 
directory listing 

FLX utility, 4-8 
ini tiali zing 

FLX utility, 4-10 
DP command 

EDI utility, 2-14, 2-31 
DSC utility 

bad block information, 8-9 
command line, 8-5 
parameter, 8-5 
stand-alone, 8-21 
data transfer, 8-24 
device support, 8-4 
error message, 8-28 
file label, 8-8 
initiating, 8-5 
operation overview, 8-19 
stand-alone 

command line, 8-21 
DSC64K. SYS, 8-23 

CNF and, 8-24 
DSCSYS.SYS, 8-19 
switch, 8-6 
on-line, 8-9 
stand-alone 

DSC64K . SYS , 8-24 
DSCSYS.SYS, 8-20 
summary, 8-7, 8-20 
terminating, 8-5 
Dumping file 

DMP utility, 11-1 
/DV switch 

VFY utility, 9-5 



ED command 

EDI utility, 2-32 
EDI utility 

character erase, 2-6 

command 

basic, 2-9 
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EDI utility 

command (Cont.) 

detailed reference summary, 
2-27 

device output, 2-26 
file I/O, 2-25 
function summary, 2-20 
locator, 2-22 
macro, 2-25 
set up, 2-21 
summary, 2-10 

text manipulation, 2-23 to 
2-24 

text modification, 2-23 to 
2-24 

control mode, 2-3 
convention 

command, 2-8 

terminal, 2-6 
error message, 2-56 

command level information, 
2-57 

fatal, 2-64 

file access, 2-60 

requiring EDI restart, 2-61 
example, 2-51 
file specification 

default, 2-2 

format, 2-2 
initiating (invoking), 2-1 
line erase, 2-7 
paging, 2-5 
RETURN key, 2-7 
text access mode, 2-3 

block mode, 2-4 

line-by-line mode, 2-4 
text file 



creating, 


2-2 


input, 2-6 




output, 2- 


6 


secondary , 


2-6 


usage notes, 


2-50 


Editor 




EDI utility, 


2-1 


/EN switch 




PIP utility, 


3-19 


END command 




EDI utility, 


2-31 


/EOF switch 




PIP utility, 


3-21 


/EP switch 




LBR utility, 


10-16 


Equal sign command 


ZAP utility, 


15-17 


ERASE command 




EDI utility, 


2-32 


/ERL switch 




FMT utility. 


5-8 


Error message 




BAD utility, 


6-10 


BRU utility, 
CMP utility, 


7-34 


12-6 


CRF utility, 
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Error message (Cont.) 

DMP utility, 11-12 

DSC utility, 8-28 

EDI utility, 2-56 

FLX utility, 4-17 

FMT utility, 5-10 

LBR utility, 10-33 

PAT utility, 14-7 

PIP utility, 3-43 

SLP utility, 13-20 

VFY utility, 9-11 

ZAP utility, 15-23 
/ERRORS qualifier 

BRU utility, 7-16 
ESCape command 

EDI utility, 2-14, 2-32 
/EX switch 

LBR utility, 10-18 

PIP utility, 3-21 
/EXCLUDE qualifier 

BRU utility, 7-16 
EXIT & DELETE command 

EDI utility, 2-32 
EXIT command 

EDI utility, 2-14, 2-27, 2-32 
/EXTEND qualifier 



BRU utility, 


7- 


16 


/FA switch 






FLX utility, 


4- 


5 


/FB switch 






FLX utility, 


4- 


5 


/FC switch 






FLX utility, 


4- 


7 


FF command 






EDI utility, 


2- 


34 


/FF switch 






CMP utility, 


12 


-3 


/FI switch 






DMP utility, 


11 


-5 


PIP utility, 


3- 


22 


File 






appending 






PIP utility, 


3- 


comparing 






CMP utility, 


12 


copying 







BRU utility, 7-1 

DOS-11, 4-3 

DSC utility, 8-1 

Files-11, 3-8 

FLX utility, 4-3 

PIP utility, 3-8 

RT-11, 4-3 
creating 

EDI utility, 2-2 
deleting 

PIP utility, 3-17 
displaying 

block number 

PIP utility, 3-25 
dumping 

DMP utility, 11-1 
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File (Cont.) 
editing 

EDI utility, 2-1 
FORTRAN direct access 

See FLX utility 
index 

listing contents 
VFY utility, 9-6 
library 

LBR utility, 10-2 
listing 

FLX utility, 4-7 

LBR utility, 10-21 

PIP utility, 3-24 
lost 

recovering 

VFY utility, 9-6 
merging 

PIP utility, 3-9 
owning 

PIP utility, 3-11 
protecting 

Files-11 

PIP utility, 3-29 
purging 

PIP utility, 3-31 
renaming 

PIP utility, 3-33 
saving 

BRU utility, 7-1 

DSC utility, 8-1 
specifying, 1-4 
spooling 

PIP utility, 3-38 
transferring 

FLX utility, 4-1 
truncating 

PIP utility, 3-40 
universal library 

See Universal library file 
updating 

PAT utility, 14-1 

PIP utility, 3-42 

SLP utility, 13-1 

ZAP utility, 15-1 
validating contents 

PAT utility, 14-6 
FILe command 

EDI utility, 2-33 
File Compare Utility 

See CMP utility 
File Dump Utility 
See DMP utility 
File Structure Verification 

Utility 
See VFY utility 
File Transfer Utility Program 

See FLX utility 
Files-11 
file 

copying 

FLX utility, 4-2 
PIP utility, 3-8 



Files-11 

file (Cont.) 

protecting 

PIP utility, 3-29 

verifying structure, 9-1 
FIND command 

EDI utility, 2-33 
FLX utility 

cassette, 4-13 

input file, 4-15 

multivolume support, 4-14 

output file, 4-14 

TA11/TU60 support, 4-13 
command line, 4-2 
device support, 4-2 
DOS-11 volume, 4-8 

deleting, 4-10 

directory listing, 4-8 

initializing, 4-10 

valid, 4-1 
error message, 4-17 
file 

deleting, 4-7 

Files-11, 4-2 

specifying, 4-2 
FORTRAN direct access file, 
4-16 

paper tape support, 4-15 

RT-11 volume, 4-10 
deleting, 4-12 
directory listing, 4-10 
initializing, 4-12 
valid, 4-2 

switch, 4-3 
control, 4-6 
transfer mode, 4-4 
volume format, 4-4 

volume 

directory listing, 4-7 
file deletion, 4-7 
file transfer, 4-4 
formatting, 4-4 
initializing, 4-2 

wildcard, 4-3 
FMT utility 

command line, 5-1 

device support, 5-5 

error message, 5-10 

indirect command file, 5-9 

initiating, 5-1 

operation mode, 5-2 

switch, 5-7 
summary, 5-1 

terminating, 5-2 
/FO switch 

PIP utility, 3-11 
FORM FEED command 

EDI utility, 2-34 
Formatting volume 

FLX utility, 4-4 

FMT utility, 5-1 
/FR switch 

PIP utility, 3-23 
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/FR switch (Cont.) 

VFY utility, 9-5 
/FU switch 

LBR utility, 10-21 

PIP utility, 3-25 

/HD switch 

DMP utility, 11-5 

VFY utility, 9-5 
/HEADERS qualifier 

BRU utility, 7-16 
/HF switch 

DMP utility, 11-6 
/HX switch 

DMP utility, 11-6 

/ID switch 

DMP utility, 11-6 

FLX utility, 4-7 

PIP utility, 3-23 
/IM switch 

FLX utility, 4-5 
/IMAGE qualifier 

BRU utiltiy, 7-17 
/IN switch 

LBR utility, 10-19 
Index file 

listing contents 
VFY utility, 9-6 
Indirect command file, 1-9 

BAD utility, 6-2 

FMT utility, 5-9 

SLP utility, 13-8 

ZAP utility, 15-6 
/INITIALIZE qualifier 

BRU utility, 7-17 
INSERT command 

EDI utility, 2-15 
/INVOLUME qualifier 

BRU utility, 7-17 

K command 

ZAP utility, 15-16 
KILL command 

EDI utility, 2-34 

/LB switch 

DMP utility, 11-6 
LBR utility 

combining library function, 

10-32 
command line, 10-8 
default, 10-8 
error message, 10-33 
library file 

creating, 10-12 

deleting, 10-13 

format, 10-2 

inserting module, 10-20 

listing, 10-21 

replacing module, 10-23 

spooling, 10-29 
restriction, 10-8 



LBR utility (Cont.) 

switch, 10-9 

universal library file 
inserting module, 10-20 
replacing module, 10-27 
LC command 

EDI utility, 2-35 
/LC switch 

DMP utility, 11-6 
/LD switch 

PIP utility, 3-17 
/LE switch 

LBR utility, 10-21 
/LENGTH qualifier 

BRU utility, 7-18 
LI command 

EDI utility, 2-35 
/LI switch 

See also /LIST switch 

CMP utility, 12-3 

FLX utility, 4-7 

LBR utility, 10-21 

PIP utility, 3-24 
/BR, 3-25 
/FU, 3-25 
/TB, 3-26 

VFY utility, 9-6 

ZAP utility, 15-2 
Librarian Utility Program 

See LBR utility 
Library file 

See LBR utility 
LINE CHANGE command 

EDI utility, 2-35 
Line Text Editor 

See EDI utility 
LIST ON PSEUDO DEVICE command 

EDI utility, 2-36 
LIST ON TERMINAL command 

EDI utility, 2-35 
/LIST switch 

See also /LIST switch 

BAD utility, 6-5 
Listing file 

FLX utility, 4-7 

PIP utility, 3-24 
/LN switch 

CMP utility, 12-3 
/LO switch 

VFY utility, 9-6 
LOCATE command 

EDI utility, 2-15, 2-36 
Lost file 

recovering 

VFY utility, 9-6 
LP command 

EDI utility, 2-36 
/LW switch 

DMP utility, 11-7 



M command 

EDI utility, 2-38 
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MACRO CALL command 

EDI utility, 2-37 
MACRO command 

EDI utility, 2-36 
MACRO EXECUTE command 

EDI utility, 2-38 
MACRO IMMEDIATE command 

EDI utility, 2-38 
MACRO- 11 

source file 

cross-referencing symbols 
CRF utility, B-l 
Magnetic tape 

See Tape 
/MANUAL switch 

BAD utility, 6-6 

FMT utility, 5-8 
/MAXIMUM qualifier 

BRU utility, 7-18 
/MB switch 

CMP utility, 12-3 
MC command 

EDI utility, 2-37 
/MD switch 

DMP utility, 11-7 
/ME switch 

PIP utility, 3-9, 3-28 
Merging file 

PIP utility, 3-9 
/MH switch 

LBR utility, 10-22 
/MOUNTED qualifier 

BRU utility, 7-18 



/NEW_VERSION qualifier 

BRU utility, 7-19 
NEXT & PRINT command 

EDI utility, 2-16, 2-39 
NEXT command 

EDI utility, 2-16, 2-39 
/NM switch 

PIP utility, 3-28 
/NOINITIALIZE qualifier 

BRU utility, 7-19 
/NOPRESERVE qualifier 

BRU utility, 7-19 
/NOSUPERSEDE qualifier 

BRU utility, 7-19 
/NOVERIFY switch 

FMT utility, 5-8 
/NOWCHK switch 

BAD utility, 6-9 
NP command 

EDI utility, 2-16, 2-39 
/NS switch 

SLP utility, 13-16 
/NU switch 

FLX utility, 4-7 
/NV subswitch 

PIP utility, 3-20 
/NV switch 

PIP utility, 3-12 



command 

ZAP utility, 15-17 
Object module 

patching 

PAT utility, 14-1 

storing in library 
LBR utility, 10-19 
Object Module Patch Utility 

See PAT utility 
/OCT switch 

DMP utility, 11-7 
ODT on-line debugger 

ZAP utility, 15-1 
OP command 

EDI utility, 2-39 
OPEN SECONDARY command 

EDI utility, 2-39 
Operator 

See SLP utility 
OU ON/OFF command 

EDI utility, 2-40 
OUTPUT ON/OFF command 

EDI utility, 2-40 
/OUTVOLUME qualifier 

BRU utility, 7-20 
OVERLAY command 

EDI utility, 2-40 
/OVERRIDE switch 

BAD utility, 6-6 
/OVR switch 

FMT utility, 5-9 



PAGe command 

EDI utility, 2-41 
PAGE FIND command 

EDI utility, 2-41 
PAGE LOCATE command 

EDI utility, 2-41 
PAste command 

EDI utility, 2-42 
PAT utility 

checksum, 14-6 

command line, 14-1 

error message, 14-7 

file 

correction, 14-3 
input, 14-3 
Task Builder, 14-4 
validating file content, 14-6 
Patching 

object module 

See PAT utility 
source file 

See SLP utility 
task image file 
See ZAP utility 
/PATTERN switch 

BAD utility, 6-6 
Percent sign 

See Wildcard 
Peripheral Interchange Program 
See PIP utility 
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PF command 

EDI utility, 2-41 
PIP utility 

command functions, 3-8 

copying Files-11 file, 3-8 

file control, 3-14 
command line, 3-1 
error code, 3-53 
error message, 3-43 
file 

deleting, 3-17 

listing, 3-24 

merging, 3-9 

protecting, 3-29 

purging, 3-31 

renaming, 3-33 

spooling, 3-38 
file specification, 3-1 

default, 3-1 to 3-2 

wildcard, 3-7 
subswitch, 3-14 

description, 3-6 

merge, 3-11 

summary, 3-3 
switch, 3-14 

description, 3-5 

summary, 3-3 
UFD creating, 3-41 
wildcard, 3-7 
PL command 

EDI utility, 2-41 
/POSITION qualifier 
BRU utility, 7-20 
/PR switch 

PIP utility, 3-29 
PRINT command 

EDI utility, 2-17, 2-42 
Protection code 
file 

PIP utility, 3-26 
/PROTECTION qualifier 

BRU utility, 7-20 
/PU switch 

PIP utility, 3-31 

Qualifier 

BRU utility, 7-12 



R command 

ZAP utility, 15-18 
/R5 switch 

DMP utility, 11-7 
/RC switch 

DMP utility, 11-7 

VFY utility, 9-7 
/RE switch 

PIP utility, 3-33 

VFY utility, 9-7 
REAd command 

EDI utility, 2-42 
RENew command 

EDI utility, 2-19, 2-43 



/RETRY switch 

BAD utility, 6-6 
RETURN command 

EDI utility, 2-19, 2-43 
RETYPE command 

EDI utility, 2-19, 2-43 
/REVISED qualifier 

BRU utility, 7-21 
/REWIND qualifier 

BRU utility, 7-21 
/RM switch 

PIP utility, 3-35 
/RO switch 

ZAP utility, 15-2 
/RP switch 

LBR utility, 10-23 
/RS switch 

FLX utility, 4-4 
SLP utility, 13-16 
/RT switch 

FLX utility, 4-4 
RT-11 

device support 

FLX utility, 4-2 
file copying 

FLX utility, 4-3 
volume 
deleting 

FLX utility, 4-12 
directory listing 

FLX utility, 4-10 
initializing 

FLX utility, 4-12 
/RW switch 

DMP utility, 11-7 
DSC utility, 8-15 
FLX utility, 4-8 
PIP utility, 3-36 

SAve command 

EDI utility, 2-44 
/SB switch 

DMP utility, 11-8 

PIP utility, 3-37 
SC command 

EDI utility, 2-44 
/SD switch 

PIP utility, 3-37 
SEARCH & CHANGE command 

EDI utility, 2-44 
SELECT PRIMARY command 

EDI utility, 2-45 
SELECT SECONDARY command 

EDI utility, 2-46 
/SF switch 

DMP utility, 11-8 
SIZE command 

EDI utility, 2-46 
/SL switch 

CMP utility, 12-3 
SLP utility 

audit trail, 13-16 

changing value, 13-17 
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SLP utility 

audit trail (Cont.) 
deleting, 13-19 
setting 

length, 13-17 
position, 13-17 
suppressing, 13-18 
checksum, 13-3 
edit command line, 13-5 
edit commands, 13-5 
error message, 13-20 
file 

input, 13-2 
listing, 13-3 
output, 13-3 
processing, 13-4 
source 

creating, 13-14 
updating, 13-9 
indirect command file, 13-8 
initiating (invoking), 13-1 
operator, 13-9 
switch, 13-14 
Source file 

See SLP utility 
Source Language Input Program 

See SLP utility 
SP command 

EDI utility, 2-45 
/SP switch 

CMP utility, 12-3 
DMP utility, 11-8 
FLX utility, 4-8 
LBR utility, 10-29 
PIP utility, 3-38 
SLP utility, 13-15 
Spooling 
file 

PIP utility, 3-38 

library file 

LBR utility, 10-29 
/SQ switch 

SLP utility, 13-16 
/SR switch 

PIP utility, 3-39 
SS command 

EDI utility, 2-46 
/SS switch 

LBR utility, 10-29 
/SU switch 

PIP utility, 3-12 
/SUPERSEDE qualifier 

BRU utility, 7-21 
Swi tch 

BAD utility, 6-5 

BRU utility, 7-12 

CMP utility, 12-2 

CRF utility, B-l 

DMP utility, 11-3 

DSC utility, 8-9 

FLX utility, 4-3 

FMT utility, 5-7 

LBR utility, 10-9 



Switch (Cont.) 

PAT utility, 14-6 
PIP utility, 3-14 
SLP utility, 13-14 
summary 

BAD, A-12 

BRU, A-13 

CMP, A-22 

DMP, A-20 

DSC, A-16 

EDI, A-l 

FLX, A-9 

FMT, A-ll 

LBR, A-l 8 

PAT, A-24 

PIP, A-5 

SLP, A-23 

VFY, A-l 7 

ZAP, A-25 
VFY utility, 9-4 
ZAP utility, 15-2 
/SZ switch 

LBR utility, 10-30 

TAB ON /OFF command 

EDI utility, 2-46 
Tape 

backing up 

BRU utility, 7-1 
comparing 

DSC utility, 8-14 
conventional backup 

BRU utility, 7-4 
copying 

BRU utility, 7-1 
data transfer 

DSC utility, 8-26 
formatting 

FLX utility, 4-4 
full backup 

BRU utility, 7-3 
mounting 

BRU utility, 7-2 
restoring 

BRU utility, 7-1 
selective backup 

BRU utility, 7-3 
setting block size 

PIP utility, 3-15 
verifying 

VFY utility, 9-1 
/TAPE_LABEL qualifier 

BRU utility, 7-21 
Task Builder 

PAT utility, 14-4 
Task image file 
patching 

ZAP utility, 15-1 
Task/File Patch Program 

See ZAP utility 
/TB switch 

CMP utility, 12-3 
PIP utility, 3-26 
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/TD switch 

PIP utility, 3-40 
/TM02 switch 

DSC utility, 8-22 
TOF command 

EDI utility, 2-19, 2-47 
TOP command 

EDI utility, 2-20, 2-47 
TOP OF FILE command 

EDI utility, 2-19, 2-47 
/TR switch 

PIP utility, 3-40 

SLP utility, 13-15 
TYpe command 

EDI utility, 2-47 

UC ON/OFF command 

EDI utility, 2-48 
/OF switch 

PIP utility, 3-41 
UFD 

creating 

PIP utility, 3-41 
listing file 

PIP utility, 3-24 
validating, 9-5 
/UFD qualifier 

BRU utility, 7-21 
/UI switch 

FLX utility, 4-8 
/UN switch 

PIP utility, 3-42 
/UNIT switch 

DSC utility, 8-22 
Universal library file 
inserting module 

LBR utility, 10-20 
replacing module 
LBR utility, 10-27 
UNSave command 

EDI utility, 2-48 
/UP switch 

PIP utility, 3-42 
VFY utility, 9-8 
/UPDATE switch 

BAD utility, 6-6 
UPPERCASE ON/OFF command 

EDI utility, 2-48 
User File Directory 

See UFD 
Utility 

command line format, 1-4 
edi ting 

EDI utility, 1-2 
file manipulation 
FLX utility, 1-2 
PIP utility, 1-2 
file specification 
default, 1-4 
format, 1-4 
indirect command file, 1-9 
invoking, 1-6 
DCL, 1-6 



Utility 

invoking (Cont.) 
installed, 1-7 
MCR, 1-6 

uninstalled, 1-9 
listed, 1-1 

program maintenance, 15-1 

CMP utility, 1-3 

PAT utility, 1-3 

SLP utility, 1-3 

ZAP utility, 1-4 
programming 

DMP utility, 1-3 

LBR utility, 1-3 
volume maintenance 

BAD utility, 1-2 

BRU utility, 1-3 

DSC utility, 1-3 

FMT utility, 1-2 

VFY utility, 1-3 

V command 

ZAP utility, 15-17 
/VB switch 

CMP utility, 12-3 
/VE switch 

FLX utility, 4-8 
/VEC switch 

BAD utility, 6-9 
DSC utility, 8-23 
Veri f ication 
device 

BAD utility, 6-3 
file structure 

VFY utility, 9-1 
task image file content 
See ZAP utility 
VERIFY ON/OFF command 

EDI utility, 2-49 
/VERIFY qualifier 

BRU utility, 7-22 
/VERIFY switch 

DSC utility, 8-18 
FMT utility, 5-9 
VFY utility 

command line, 9-2 
error message, 9-11 
file error reporting, 9-8 
operation mode, 9-3 
switch, 9-4 

summary, 9-4 
validity check, 9-3 
Volume 

backing up 

BRU utility, 7-1 
compressing 

DSC utility, 8-3 
directory listing 

FLX utility, 4-7 
displaying free space 
PIP utility, 3-23 
VFY utility, 9-5 
examining data 
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Volume 

examining data (Cont.) 

DMP utility, 11-1 
file 

deleting 

FLX utility, 4-7 
recovering lost 

VFY utility, 9-6 
transferring 

FLX utility, 4-4 
formatting 

FLX utility, 4-4 
FMT utility, 5-1 
ini tiali zing 

BRU utility, 7-17 
FLX utility, 4-2 
listing file-ID 

VFY utility, 9-6 
locating bad block 
BAD utility, 6-1 
FMT utility, 5-1 
VFY utility, 9-7 
recovering 
lost block 

VFY utility, 9-7 
lost file 

VFY utility, 9-6 
space 

DSC utility, 8-3 
restoring 

BRU utility, 7-1 
verifying, 9-1 
block 

VFY utility, 9-7 

/WCHK switch 

BAD utility, 6-9 
/WD switch 

DMP utility, 11-8 
Wildcard 

file specification 
BRU utility, 7-7 
FLX utility, 4-3 
PIP utility, 3-7 
/WINDOWS qualifier 

BRU utility, 7-22 
/WLT switch 

FMT utility, 5-9 



WRITE command 

EDI utility, 2-49 

X command 

ZAP utility, 15-16 

/@Y switch 

FMT utility, 5-9 



ZAP utility 

address boundary 

displaying, 15-3 
addressing mode, 15-4 
command 

carriage return, 15-7 

general purpose, 15-7 
summary, 15-15 

open/close location, 15-7 
summary, 15-11 
command line, 15-6 

element, 15-8 
error message, 15-23 
example, 15-18 
indirect command file, 15-6 
initiating (invoking), 15-5 
location 

addressing, 15-4 

closing, 15-13 

contents 

changing, 15-13 
displaying, 15-12 
verifying, 15-18 

opening, 15-12 

specifying, 15-10 
ODT on-line debugger, 15-1 
operating mode, 15-2 
register 

setting value, 15-18 
relocation biases, 15-4 
switch, 15-2 
task image file, 15-3 

I- and D-space, 15-3 

multiuser, 15-3 

resident library, 15-3 
terminating, 15-5 
/ZE switch 

FLX utility, 4-8 
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READER'S COMMENTS 

NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 
company's discretion. If you require a written reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 



Did you find this manual understandable, usable, and well organized? Please make suggestions for improvement. 



Did you find errors in this manual? If so, specify the error and the page number. 



Please indicate the type of user/reader that you most nearly represent. 

□ Assembly language programmer 

□ Higher-level language programmer 

□ Occasional programmer (experienced) 

□ User with little programming experience 

□ Student programmer 

□ Other (please specify) 

Name Date 

Organization 

Street 

City State Zip Code _ 

or Country 
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